@caperjs/core 0.7.2 → 0.7.4

package/src/ui/UICanvas.test.ts

@@ -23,7 +23,7 @@ vi.mock('../core/Application', async () => {
 // constructed. See importOrder.containerFirst.test.ts.
 import '../mixins/factory/const';
 import { Signal } from '../signals';
-import { computeEffectivePadding, UICanvas } from './UICanvas';
+import { computeEffectivePadding, resolveSafeArea, UICanvas } from './UICanvas';
 
 const zero = { top: 0, right: 0, bottom: 0, left: 0 };
 
@@ -51,6 +51,28 @@ describe('computeEffectivePadding', () => {
   });
 });
 
+describe('resolveSafeArea', () => {
+  const insets = { top: 51, right: 4, bottom: 34, left: 4 };
+
+  it('keeps every inset when useSafeArea is true', () => {
+    expect(resolveSafeArea(insets, true)).toEqual(insets);
+  });
+
+  it('drops every inset when useSafeArea is false', () => {
+    expect(resolveSafeArea(insets, false)).toEqual(zero);
+  });
+
+  it('drops only the edges set to false, keeping the ones left out', () => {
+    expect(resolveSafeArea(insets, { top: false })).toEqual({ top: 0, right: 4, bottom: 34, left: 4 });
+    expect(resolveSafeArea(insets, { top: false, bottom: true, left: false })).toEqual({
+      top: 0,
+      right: 4,
+      bottom: 34,
+      left: 0,
+    });
+  });
+});
+
 describe('UICanvas element reordering', () => {
   let app: any;
   let originalAppDescriptor: PropertyDescriptor | undefined;

package/src/ui/UICanvas.ts

@@ -73,11 +73,18 @@ export type UICanvasConfig = {
   padding: Padding;
   size: Size;
   useAppSize: boolean;
-  useSafeArea: boolean;
+  useSafeArea: UICanvasSafeArea;
   layout?: Omit<LayoutOptions, 'target'> | null | boolean;
   autoLayoutChildren?: boolean;
 };
 
+/**
+ * Which device safe-area insets the canvas pads by: `true` (all four, the default), `false`
+ * (none), or per edge, where an edge left out stays on. `{ top: false }` lets top-row UI sit
+ * in the camera strip of a punch-hole phone while the bottom still clears the gesture bar.
+ */
+export type UICanvasSafeArea = boolean | Partial<Record<keyof Padding, boolean>>;
+
 export const UICanvasConfigKeys: (keyof UICanvasConfig)[] = [
   'debug',
   'padding',
@@ -92,7 +99,7 @@ export type UICanvasProps = {
   padding: Partial<Padding> | PointLike;
   size?: SizeLike;
   useAppSize?: boolean;
-  useSafeArea?: boolean;
+  useSafeArea?: UICanvasSafeArea;
   layout?: Omit<LayoutOptions, 'target'> | null | boolean;
   autoLayoutChildren?: boolean;
 };
@@ -113,6 +120,18 @@ export function computeEffectivePadding(padding: Padding, safeArea: Padding): Pa
   };
 }
 
+/** The safe-area insets `useSafeArea` keeps: all, none, or the edges not set to `false`. */
+export function resolveSafeArea(safeArea: Padding, useSafeArea: UICanvasSafeArea): Padding {
+  if (useSafeArea === true) return { ...safeArea };
+  if (useSafeArea === false) return { ...zeroPadding };
+  return {
+    top: useSafeArea.top === false ? 0 : safeArea.top,
+    right: useSafeArea.right === false ? 0 : safeArea.right,
+    bottom: useSafeArea.bottom === false ? 0 : safeArea.bottom,
+    left: useSafeArea.left === false ? 0 : safeArea.left,
+  };
+}
+
 const defaultLayout = {
   flexGrow: 0,
   flexShrink: 0,
@@ -449,7 +468,7 @@ export class UICanvas extends _UICanvas {
   private _applyPadding() {
     const padding = computeEffectivePadding(
       this.config.padding,
-      this.config.useSafeArea ? this.app.safeArea : zeroPadding,
+      resolveSafeArea(this.app.safeArea, this.config.useSafeArea),
     );
     this.layout = {
       paddingLeft: padding.left,

package/src/utils/index.ts

@@ -13,6 +13,7 @@ export * from './math';
 export * from './misc';
 export * from './number';
 export * from './object';
+export * from './orientation';
 export * from './padding';
 export * from './pixi';
 export * from './platform';

package/src/utils/orientation.d.ts

@@ -0,0 +1,44 @@
+/** The orientation a game is locked to. */
+export type OrientationLock = 'portrait' | 'landscape';
+
+/** `orientation.overlay` in `caper.config.ts`: restyle or replace the web "rotate your device" overlay. */
+export interface OrientationOverlayOptions {
+  /** Default: "Rotate your device" (portrait) / "Turn your device sideways" (landscape). */
+  text?: string;
+  /** CSS background. Default `#000`. */
+  background?: string;
+  /** CSS text color. Default `#fff`. */
+  color?: string;
+  /** CSS font family. Default: the system font. */
+  fontFamily?: string;
+  /** Class(es) added to the overlay so a game can style it with its own CSS. */
+  className?: string;
+  /** Build the whole overlay yourself; replaces the default element. Called once, when first shown. */
+  element?: () => HTMLElement;
+}
+
+/**
+ * `orientation` in `caper.config.ts`: a lock, or `{ lock, overlay }`. The string
+ * form is shorthand for `{ lock }` with the default overlay. `overlay: false`
+ * turns off the web overlay and its pause.
+ */
+export type OrientationConfig =
+  | OrientationLock
+  | {
+      lock: OrientationLock;
+      overlay?: false | OrientationOverlayOptions;
+    };
+
+/** `orientation` normalized by `resolveOrientation`. */
+export interface ResolvedOrientation {
+  lock: OrientationLock;
+  /** `false` (no overlay, no pause) or the overlay options (`{}` for the default look). */
+  overlay: false | OrientationOverlayOptions;
+}
+
+/**
+ * `orientation` as `{ lock, overlay }`, or `null` when unset. The string form is
+ * shorthand for `{ lock }`; a missing `overlay` means the default overlay (`{}`).
+ * Throws a `TypeError` on anything else.
+ */
+export declare function resolveOrientation(orientation: unknown): ResolvedOrientation | null;

package/src/utils/orientation.js

@@ -0,0 +1,37 @@
+/**
+ * The one normalizer for `caper.config.ts`'s `orientation`, shared by the
+ * runtime `orientation` plugin, the native CLI, `caper doctor` and the PWA
+ * default. Plain ESM with a hand-written `orientation.d.ts` beside it, so the
+ * Node CLI (`cli/`, `build/`) can import it without a TypeScript step. Keep it
+ * dependency-free and free of browser globals.
+ */
+
+const LOCKS = ['portrait', 'landscape'];
+
+/**
+ * `orientation` as `{ lock, overlay }`, or `null` when unset. The string form is
+ * shorthand for `{ lock }`; a missing `overlay` means the default overlay (`{}`).
+ * Throws on anything else.
+ *
+ * @param {unknown} orientation
+ */
+export function resolveOrientation(orientation) {
+  if (orientation === undefined || orientation === null) return null;
+  if (typeof orientation === 'string') {
+    if (!LOCKS.includes(orientation)) {
+      throw new TypeError(`orientation must be 'portrait' or 'landscape' (got ${JSON.stringify(orientation)})`);
+    }
+    return { lock: orientation, overlay: {} };
+  }
+  if (typeof orientation === 'object' && !Array.isArray(orientation)) {
+    const { lock, overlay } = orientation;
+    if (!LOCKS.includes(lock)) {
+      throw new TypeError(`orientation.lock must be 'portrait' or 'landscape' (got ${JSON.stringify(lock)})`);
+    }
+    if (overlay !== undefined && overlay !== false && (overlay === null || typeof overlay !== 'object')) {
+      throw new TypeError(`orientation.overlay must be false or an object (got ${JSON.stringify(overlay)})`);
+    }
+    return { lock, overlay: overlay ?? {} };
+  }
+  throw new TypeError(`orientation must be 'portrait', 'landscape', or { lock, overlay? } (got ${JSON.stringify(orientation)})`);
+}

package/src/utils/orientation.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from 'vitest';
+import { resolveOrientation } from './orientation';
+
+describe('resolveOrientation', () => {
+  it('is null when unset', () => {
+    expect(resolveOrientation(undefined)).toBeNull();
+    expect(resolveOrientation(null)).toBeNull();
+  });
+
+  it.each(['portrait', 'landscape'] as const)('expands the %s shorthand with the default overlay', (lock) => {
+    expect(resolveOrientation(lock)).toEqual({ lock, overlay: {} });
+  });
+
+  it('keeps the object form, defaulting the overlay', () => {
+    expect(resolveOrientation({ lock: 'landscape' })).toEqual({ lock: 'landscape', overlay: {} });
+  });
+
+  it('passes overlay options and false through', () => {
+    const overlay = { text: 'Hold your phone upright to play' };
+    expect(resolveOrientation({ lock: 'portrait', overlay })).toEqual({ lock: 'portrait', overlay });
+    expect(resolveOrientation({ lock: 'portrait', overlay: false })).toEqual({ lock: 'portrait', overlay: false });
+  });
+
+  it.each(['any', 'Portrait', 1, true, {}, { lock: 'any' }, { overlay: false }, { lock: 'portrait', overlay: 'off' }])(
+    'throws on %o',
+    (value) => {
+      expect(() => resolveOrientation(value)).toThrow(/orientation/);
+    },
+  );
+});

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated during the build process.
-export const version: string = '0.7.2';
+export const version: string = '0.7.4';
 export const pixiVersion: string = '8.22.0';