@biela.dev/core 1.5.0 → 1.6.0

package/dist/index.d.cts

@@ -158,6 +158,27 @@ interface ScreenPowerState {
  */
 declare function useScreenPower(): ScreenPowerState;
 
+interface UseOrientationResult {
+    /** Current orientation */
+    orientation: "portrait" | "landscape";
+    /** Convenience boolean */
+    isLandscape: boolean;
+    /** Toggle between portrait and landscape */
+    toggle: () => void;
+    /** Set orientation directly */
+    setOrientation: (o: "portrait" | "landscape") => void;
+}
+/**
+ * Hook for managing device orientation state with a toggle function.
+ *
+ * ```tsx
+ * const { orientation, toggle } = useOrientation();
+ * <button onClick={toggle}>Rotate</button>
+ * <DeviceFrame deviceId="iphone-17-pro" orientation={orientation} />
+ * ```
+ */
+declare function useOrientation(initial?: "portrait" | "landscape"): UseOrientationResult;
+
 /**
  * Resolve device SVG component by ID.
  * This is a lookup registry — devices register their SVG components here.
@@ -212,7 +233,9 @@ interface SVGScreenRect {
 declare function registerCustomDeviceSVG(deviceId: string, svgString: string, frame: FrameInfo, cropViewBox?: SVGCropArea, screenRect?: SVGScreenRect): void;
 interface DeviceFrameProps {
     /** Device ID e.g. "iphone-16-pro" */
-    device: string;
+    device?: string;
+    /** Alias for device — accepts either prop name */
+    deviceId?: string;
     /** Orientation */
     orientation?: "portrait" | "landscape";
     /** Scale mode: "fit" auto-scales, "manual" uses manualScale value */
@@ -252,7 +275,45 @@ interface DeviceFrameProps {
  *                 └── SafeAreaOverlay (optional dev tool)
  *           └── ScaleBar (outside scaler, in normal flow)
  */
-declare function DeviceFrame({ device, orientation, scaleMode, manualScale, showSafeAreaOverlay, showScaleBar, colorScheme, onContractReady, onScaleChange, children, }: DeviceFrameProps): react_jsx_runtime.JSX.Element;
+declare function DeviceFrame({ device: deviceProp, deviceId, orientation, scaleMode, manualScale, showSafeAreaOverlay, showScaleBar, colorScheme, onContractReady, onScaleChange, children, }: DeviceFrameProps): react_jsx_runtime.JSX.Element;
+
+interface DeviceCompareProps {
+    /** First device ID */
+    deviceA: string;
+    /** Second device ID */
+    deviceB: string;
+    /** Orientation for both devices */
+    orientation?: "portrait" | "landscape";
+    /** Frame color scheme */
+    colorScheme?: "light" | "dark";
+    /** Show safe area overlays */
+    showSafeAreaOverlay?: boolean;
+    /** Show scale bars */
+    showScaleBar?: boolean;
+    /** Layout direction — "auto" picks row for portrait, column for landscape */
+    layout?: "horizontal" | "vertical" | "auto";
+    /** Gap between the two frames in px (default: 24) */
+    gap?: number;
+    /** Content rendered inside BOTH device frames */
+    children?: ReactNode;
+    /** Content for device A only (overrides children for A) */
+    childrenA?: ReactNode;
+    /** Content for device B only (overrides children for B) */
+    childrenB?: ReactNode;
+    /** Callback when device A contract is ready */
+    onContractReadyA?: (dlc: DeviceLayoutContract) => void;
+    /** Callback when device B contract is ready */
+    onContractReadyB?: (dlc: DeviceLayoutContract) => void;
+}
+/**
+ * DeviceCompare — renders two device frames side-by-side for comparison.
+ *
+ * Layout defaults to "auto": horizontal (row) in portrait, vertical (column) in landscape.
+ * Each frame auto-scales independently to fit its half of the container.
+ *
+ * Must be placed inside a container with explicit width and height.
+ */
+declare function DeviceCompare({ deviceA, deviceB, orientation, colorScheme, showSafeAreaOverlay, showScaleBar, layout, gap, children, childrenA, childrenB, onContractReadyA, onContractReadyB, }: DeviceCompareProps): react_jsx_runtime.JSX.Element;
 
 interface Props {
     children: ReactNode;
@@ -405,4 +466,46 @@ interface StatusBarIndicatorsProps {
  */
 declare function StatusBarIndicators({ platform, colorScheme }: StatusBarIndicatorsProps): react_jsx_runtime.JSX.Element;
 
-export { type AdaptiveScaleResult, type ButtonName, DeviceErrorBoundary, DeviceFrame, type DeviceFrameProps, DynamicStatusBar, HardwareButtons, SCALE_STEPS, type SVGCropArea, type SVGScreenRect, SafeAreaOverlay, SafeAreaView, ScaleBar, type ScreenPowerState, StatusBarIndicators, type UseAdaptiveScaleOptions, VolumeHUD, type VolumeState, computeAdaptiveScale, computeFullScale, computeHostSize, ptsToPercent, ptsToPx, pxToPts, registerCustomDeviceSVG, registerDeviceSVG, scaleValue, snapToStep, useAdaptiveScale, useContainerSize, useDeviceContract, useScreenPower, useVolumeControl };
+interface SVGOverrideEntry {
+    deviceId: string;
+    svgString: string;
+    bezelTop: number;
+    bezelBottom: number;
+    bezelLeft: number;
+    bezelRight: number;
+    screenRect?: SVGScreenRect;
+    updatedAt: string;
+}
+/**
+ * Persistent storage for custom SVG overrides.
+ *
+ * When a user uploads a custom SVG frame for a device, it's stored in
+ * localStorage and automatically applied on subsequent imports.
+ *
+ * SSR-safe: falls back to no-op storage when localStorage is unavailable.
+ */
+declare class CustomSVGStore {
+    private storage;
+    constructor(storage?: Storage | null);
+    /** Load all stored overrides */
+    getAll(): Record<string, SVGOverrideEntry>;
+    /** Save an override and register it in the SVG registry */
+    save(entry: SVGOverrideEntry): void;
+    /** Remove an override (revert to built-in) */
+    remove(deviceId: string): void;
+    /** Check if a device has a custom override */
+    has(deviceId: string): boolean;
+    /** Get a single override by device ID */
+    get(deviceId: string): SVGOverrideEntry | undefined;
+    /**
+     * Apply all stored overrides to the SVG registry.
+     * Called during auto-registration to restore user customizations.
+     */
+    applyAll(): void;
+    private applyEntry;
+    private persist;
+}
+/** Get the default CustomSVGStore instance (singleton, uses localStorage) */
+declare function getCustomSVGStore(): CustomSVGStore;
+
+export { type AdaptiveScaleResult, type ButtonName, CustomSVGStore, DeviceCompare, type DeviceCompareProps, DeviceErrorBoundary, DeviceFrame, type DeviceFrameProps, DynamicStatusBar, HardwareButtons, SCALE_STEPS, type SVGCropArea, type SVGOverrideEntry, type SVGScreenRect, SafeAreaOverlay, SafeAreaView, ScaleBar, type ScreenPowerState, StatusBarIndicators, type UseAdaptiveScaleOptions, type UseOrientationResult, VolumeHUD, type VolumeState, computeAdaptiveScale, computeFullScale, computeHostSize, getCustomSVGStore, ptsToPercent, ptsToPx, pxToPts, registerCustomDeviceSVG, registerDeviceSVG, scaleValue, snapToStep, useAdaptiveScale, useContainerSize, useDeviceContract, useOrientation, useScreenPower, useVolumeControl };

package/dist/index.d.ts

@@ -158,6 +158,27 @@ interface ScreenPowerState {
  */
 declare function useScreenPower(): ScreenPowerState;
 
+interface UseOrientationResult {
+    /** Current orientation */
+    orientation: "portrait" | "landscape";
+    /** Convenience boolean */
+    isLandscape: boolean;
+    /** Toggle between portrait and landscape */
+    toggle: () => void;
+    /** Set orientation directly */
+    setOrientation: (o: "portrait" | "landscape") => void;
+}
+/**
+ * Hook for managing device orientation state with a toggle function.
+ *
+ * ```tsx
+ * const { orientation, toggle } = useOrientation();
+ * <button onClick={toggle}>Rotate</button>
+ * <DeviceFrame deviceId="iphone-17-pro" orientation={orientation} />
+ * ```
+ */
+declare function useOrientation(initial?: "portrait" | "landscape"): UseOrientationResult;
+
 /**
  * Resolve device SVG component by ID.
  * This is a lookup registry — devices register their SVG components here.
@@ -212,7 +233,9 @@ interface SVGScreenRect {
 declare function registerCustomDeviceSVG(deviceId: string, svgString: string, frame: FrameInfo, cropViewBox?: SVGCropArea, screenRect?: SVGScreenRect): void;
 interface DeviceFrameProps {
     /** Device ID e.g. "iphone-16-pro" */
-    device: string;
+    device?: string;
+    /** Alias for device — accepts either prop name */
+    deviceId?: string;
     /** Orientation */
     orientation?: "portrait" | "landscape";
     /** Scale mode: "fit" auto-scales, "manual" uses manualScale value */
@@ -252,7 +275,45 @@ interface DeviceFrameProps {
  *                 └── SafeAreaOverlay (optional dev tool)
  *           └── ScaleBar (outside scaler, in normal flow)
  */
-declare function DeviceFrame({ device, orientation, scaleMode, manualScale, showSafeAreaOverlay, showScaleBar, colorScheme, onContractReady, onScaleChange, children, }: DeviceFrameProps): react_jsx_runtime.JSX.Element;
+declare function DeviceFrame({ device: deviceProp, deviceId, orientation, scaleMode, manualScale, showSafeAreaOverlay, showScaleBar, colorScheme, onContractReady, onScaleChange, children, }: DeviceFrameProps): react_jsx_runtime.JSX.Element;
+
+interface DeviceCompareProps {
+    /** First device ID */
+    deviceA: string;
+    /** Second device ID */
+    deviceB: string;
+    /** Orientation for both devices */
+    orientation?: "portrait" | "landscape";
+    /** Frame color scheme */
+    colorScheme?: "light" | "dark";
+    /** Show safe area overlays */
+    showSafeAreaOverlay?: boolean;
+    /** Show scale bars */
+    showScaleBar?: boolean;
+    /** Layout direction — "auto" picks row for portrait, column for landscape */
+    layout?: "horizontal" | "vertical" | "auto";
+    /** Gap between the two frames in px (default: 24) */
+    gap?: number;
+    /** Content rendered inside BOTH device frames */
+    children?: ReactNode;
+    /** Content for device A only (overrides children for A) */
+    childrenA?: ReactNode;
+    /** Content for device B only (overrides children for B) */
+    childrenB?: ReactNode;
+    /** Callback when device A contract is ready */
+    onContractReadyA?: (dlc: DeviceLayoutContract) => void;
+    /** Callback when device B contract is ready */
+    onContractReadyB?: (dlc: DeviceLayoutContract) => void;
+}
+/**
+ * DeviceCompare — renders two device frames side-by-side for comparison.
+ *
+ * Layout defaults to "auto": horizontal (row) in portrait, vertical (column) in landscape.
+ * Each frame auto-scales independently to fit its half of the container.
+ *
+ * Must be placed inside a container with explicit width and height.
+ */
+declare function DeviceCompare({ deviceA, deviceB, orientation, colorScheme, showSafeAreaOverlay, showScaleBar, layout, gap, children, childrenA, childrenB, onContractReadyA, onContractReadyB, }: DeviceCompareProps): react_jsx_runtime.JSX.Element;
 
 interface Props {
     children: ReactNode;
@@ -405,4 +466,46 @@ interface StatusBarIndicatorsProps {
  */
 declare function StatusBarIndicators({ platform, colorScheme }: StatusBarIndicatorsProps): react_jsx_runtime.JSX.Element;
 
-export { type AdaptiveScaleResult, type ButtonName, DeviceErrorBoundary, DeviceFrame, type DeviceFrameProps, DynamicStatusBar, HardwareButtons, SCALE_STEPS, type SVGCropArea, type SVGScreenRect, SafeAreaOverlay, SafeAreaView, ScaleBar, type ScreenPowerState, StatusBarIndicators, type UseAdaptiveScaleOptions, VolumeHUD, type VolumeState, computeAdaptiveScale, computeFullScale, computeHostSize, ptsToPercent, ptsToPx, pxToPts, registerCustomDeviceSVG, registerDeviceSVG, scaleValue, snapToStep, useAdaptiveScale, useContainerSize, useDeviceContract, useScreenPower, useVolumeControl };
+interface SVGOverrideEntry {
+    deviceId: string;
+    svgString: string;
+    bezelTop: number;
+    bezelBottom: number;
+    bezelLeft: number;
+    bezelRight: number;
+    screenRect?: SVGScreenRect;
+    updatedAt: string;
+}
+/**
+ * Persistent storage for custom SVG overrides.
+ *
+ * When a user uploads a custom SVG frame for a device, it's stored in
+ * localStorage and automatically applied on subsequent imports.
+ *
+ * SSR-safe: falls back to no-op storage when localStorage is unavailable.
+ */
+declare class CustomSVGStore {
+    private storage;
+    constructor(storage?: Storage | null);
+    /** Load all stored overrides */
+    getAll(): Record<string, SVGOverrideEntry>;
+    /** Save an override and register it in the SVG registry */
+    save(entry: SVGOverrideEntry): void;
+    /** Remove an override (revert to built-in) */
+    remove(deviceId: string): void;
+    /** Check if a device has a custom override */
+    has(deviceId: string): boolean;
+    /** Get a single override by device ID */
+    get(deviceId: string): SVGOverrideEntry | undefined;
+    /**
+     * Apply all stored overrides to the SVG registry.
+     * Called during auto-registration to restore user customizations.
+     */
+    applyAll(): void;
+    private applyEntry;
+    private persist;
+}
+/** Get the default CustomSVGStore instance (singleton, uses localStorage) */
+declare function getCustomSVGStore(): CustomSVGStore;
+
+export { type AdaptiveScaleResult, type ButtonName, CustomSVGStore, DeviceCompare, type DeviceCompareProps, DeviceErrorBoundary, DeviceFrame, type DeviceFrameProps, DynamicStatusBar, HardwareButtons, SCALE_STEPS, type SVGCropArea, type SVGOverrideEntry, type SVGScreenRect, SafeAreaOverlay, SafeAreaView, ScaleBar, type ScreenPowerState, StatusBarIndicators, type UseAdaptiveScaleOptions, type UseOrientationResult, VolumeHUD, type VolumeState, computeAdaptiveScale, computeFullScale, computeHostSize, getCustomSVGStore, ptsToPercent, ptsToPx, pxToPts, registerCustomDeviceSVG, registerDeviceSVG, scaleValue, snapToStep, useAdaptiveScale, useContainerSize, useDeviceContract, useOrientation, useScreenPower, useVolumeControl };