@mmtitanl/tablets-core 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,330 @@
+import * as react from 'react';
+import { RefObject, ComponentType, CSSProperties, ReactNode, Component, ErrorInfo, ReactElement } from 'react';
+import { DeviceMeta, DeviceLayoutContract, SVGScreenRect } from '@mmtitanl/tablets';
+export { SVGScreenRect } from '@mmtitanl/tablets';
+
+declare function ptsToPx(pts: number, dpr: number): number;
+declare function pxToPts(px: number, dpr: number): number;
+declare function ptsToPercent(pts: number, total: number): number;
+declare function scaleValue(value: number, scaleFactor: number): number;
+declare const SCALE_STEPS: readonly [0.25, 0.33, 0.5, 0.75, 1];
+declare function computeAdaptiveScale(deviceWidth: number, deviceHeight: number, containerWidth: number, containerHeight: number, padding?: number, maxScale?: number, minScale?: number): number;
+declare function snapToStep(raw: number): number;
+declare function computeHostSize(deviceWidth: number, deviceHeight: number, scale: number): {
+    width: number;
+    height: number;
+};
+interface AdaptiveScaleResult {
+    scale: number;
+    scaledWidth: number;
+    scaledHeight: number;
+    deviceWidth: number;
+    deviceHeight: number;
+    isAtMaxScale: boolean;
+    isConstrained: boolean;
+    scalePercent: string;
+}
+declare function computeFullScale(deviceWidth: number, deviceHeight: number, containerWidth: number, containerHeight: number, options?: {
+    padding?: number;
+    maxScale?: number;
+    minScale?: number;
+    snapToSteps?: boolean;
+}): AdaptiveScaleResult;
+
+interface ContainerSize {
+    width: number;
+    height: number;
+}
+declare function useContainerSize(ref: RefObject<HTMLElement | null>): ContainerSize;
+
+interface UseAdaptiveScaleOptions {
+    device: DeviceMeta;
+    containerWidth: number;
+    containerHeight: number;
+    padding?: number;
+    maxScale?: number;
+    minScale?: number;
+    snapToSteps?: boolean;
+    orientation?: "portrait" | "landscape";
+}
+declare function useAdaptiveScale(options: UseAdaptiveScaleOptions): AdaptiveScaleResult;
+
+interface UseDeviceContractResult {
+    contract: DeviceLayoutContract;
+    cssVariables: DeviceLayoutContract["cssVariables"];
+    contentZone: DeviceLayoutContract["contentZone"]["portrait"];
+}
+declare function useDeviceContract(deviceId: string, orientation?: "portrait" | "landscape"): UseDeviceContractResult;
+
+interface UseOrientationResult {
+    orientation: "portrait" | "landscape";
+    isLandscape: boolean;
+    toggle: () => void;
+    setOrientation: (o: "portrait" | "landscape") => void;
+}
+/**
+ * Hook for managing tablet orientation state with a toggle function.
+ *
+ * ```tsx
+ * const { orientation, toggle } = useOrientation();
+ * <button onClick={toggle}>Rotate</button>
+ * <DeviceFrame deviceId="ipad-pro-13" orientation={orientation} />
+ * ```
+ */
+declare function useOrientation(initial?: "portrait" | "landscape"): UseOrientationResult;
+
+interface VolumeState {
+    level: number;
+    muted: boolean;
+    hudVisible: boolean;
+    volumeUp: () => void;
+    volumeDown: () => void;
+    toggleMute: () => void;
+}
+declare function useVolumeControl(initialVolume?: number): VolumeState;
+
+interface ScreenPowerState {
+    isOff: boolean;
+    toggle: () => void;
+}
+declare function useScreenPower(): ScreenPowerState;
+
+interface DeviceFrameInsets {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+interface DeviceFrameInfo {
+    insets: DeviceFrameInsets;
+    vars: Record<string, string>;
+    platform: "ios" | "android" | null;
+    deviceId: string | null;
+    orientation: "portrait" | "landscape" | null;
+    isReady: boolean;
+    reportColorScheme: (scheme: "light" | "dark") => void;
+}
+declare function useDeviceFrame(): DeviceFrameInfo;
+
+type FoldState = "folded" | "open";
+interface UseFoldStateResult {
+    foldState: FoldState;
+    isOpen: boolean;
+    deviceId: string;
+    toggle: () => void;
+    setFoldState: (state: FoldState) => void;
+}
+/**
+ * Manages fold state for foldable tablet devices.
+ * Convention: the open variant uses `${baseDeviceId}-open`.
+ */
+declare function useFoldState(baseDeviceId: string, initial?: FoldState): UseFoldStateResult;
+
+declare const BIELA_PREFIX: "biela:";
+interface BielaDeviceInfoMessage {
+    type: "biela:deviceInfo";
+    payload: {
+        vars: Record<string, string>;
+        platform: "ios" | "android";
+        deviceId: string;
+        orientation: "portrait" | "landscape";
+    };
+}
+interface BielaRequestMessage {
+    type: "biela:requestDeviceInfo";
+}
+interface BielaColorSchemeMessage {
+    type: "biela:colorScheme";
+    payload: {
+        scheme: "light" | "dark";
+    };
+}
+declare function isBielaMessage(data: unknown): data is {
+    type: string;
+};
+
+type DeviceSVGComponent = ComponentType<{
+    colorScheme?: "light" | "dark";
+    style?: CSSProperties;
+}>;
+interface FrameInfo {
+    bezelTop: number;
+    bezelBottom: number;
+    bezelLeft: number;
+    bezelRight: number;
+    totalWidth: number;
+    totalHeight: number;
+    screenWidth: number;
+    screenHeight: number;
+    screenRadius: number;
+    /** Optional per-edge overrides. Fall back to screenRadius when unset. */
+    screenRadiusTop?: number;
+    screenRadiusBottom?: number;
+}
+interface SVGCropArea {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface LandscapeSVGRegistration {
+    svgString: string;
+    frame: FrameInfo;
+    cropViewBox?: SVGCropArea;
+    screenRect?: SVGScreenRect;
+}
+interface LandscapeBuiltinRegistration {
+    component: DeviceSVGComponent;
+    frame: FrameInfo;
+    screenRect?: SVGScreenRect;
+}
+declare function registerDeviceSVG(deviceId: string, component: DeviceSVGComponent, frame: FrameInfo, screenRect?: SVGScreenRect, landscape?: LandscapeBuiltinRegistration): void;
+declare function registerCustomDeviceSVG(deviceId: string, svgString: string, frame: FrameInfo, cropViewBox?: SVGCropArea, screenRect?: SVGScreenRect, landscape?: LandscapeSVGRegistration): void;
+
+interface DeviceFrameProps {
+    device?: string;
+    deviceId?: string;
+    orientation?: "portrait" | "landscape";
+    scaleMode?: "fit" | "manual" | "steps";
+    manualScale?: number;
+    showSafeAreaOverlay?: boolean;
+    showDLCPanel?: boolean;
+    showScaleBar?: boolean;
+    showStatusBar?: boolean;
+    colorScheme?: "light" | "dark";
+    iframeRef?: RefObject<HTMLIFrameElement | null>;
+    onColorSchemeChange?: (scheme: "light" | "dark") => void;
+    onContractReady?: (dlc: DeviceLayoutContract) => void;
+    onScaleChange?: (scale: number) => void;
+    children?: ReactNode;
+}
+declare function DeviceFrame({ device, deviceId, orientation, scaleMode, manualScale, showSafeAreaOverlay, showScaleBar, showStatusBar, colorScheme, iframeRef, onColorSchemeChange, onContractReady, onScaleChange, children, }: DeviceFrameProps): react.JSX.Element;
+
+interface DeviceCompareProps {
+    deviceA: string;
+    deviceB: string;
+    orientation?: "portrait" | "landscape";
+    colorScheme?: "light" | "dark";
+    showSafeAreaOverlay?: boolean;
+    showScaleBar?: boolean;
+    layout?: "horizontal" | "vertical" | "auto";
+    gap?: number;
+    children?: ReactNode;
+    childrenA?: ReactNode;
+    childrenB?: ReactNode;
+    onContractReadyA?: (dlc: DeviceLayoutContract) => void;
+    onContractReadyB?: (dlc: DeviceLayoutContract) => void;
+}
+declare function DeviceCompare({ deviceA, deviceB, orientation, colorScheme, showSafeAreaOverlay, showScaleBar, layout, gap, children, childrenA, childrenB, onContractReadyA, onContractReadyB, }: DeviceCompareProps): react.JSX.Element;
+
+interface Props {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+declare class DeviceErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    render(): ReactNode;
+}
+
+interface SafeAreaViewProps {
+    edges?: Array<"top" | "bottom" | "left" | "right">;
+    children: ReactNode;
+    style?: CSSProperties;
+}
+declare function SafeAreaView({ edges, children, style }: SafeAreaViewProps): react.JSX.Element;
+
+interface SafeAreaOverlayProps {
+    contract: DeviceLayoutContract;
+    orientation: "portrait" | "landscape";
+}
+declare function SafeAreaOverlay({ contract, orientation }: SafeAreaOverlayProps): react.JSX.Element;
+
+interface ScaleBarProps {
+    deviceName: string;
+    deviceWidth: number;
+    deviceHeight: number;
+    scale: number;
+    scalePercent: string;
+    isAtMaxScale: boolean;
+    isConstrained: boolean;
+    onScaleChange?: (scale: number) => void;
+    onFit?: () => void;
+    onRealSize?: () => void;
+}
+declare function ScaleBar({ deviceName, deviceWidth, deviceHeight, scale, scalePercent, isAtMaxScale, onScaleChange, onFit, onRealSize, }: ScaleBarProps): react.JSX.Element;
+
+interface VolumeHUDProps {
+    level: number;
+    muted: boolean;
+    visible: boolean;
+    platform: "ios" | "android";
+}
+declare function VolumeHUD({ level, muted, visible, platform }: VolumeHUDProps): react.JSX.Element | null;
+
+type ButtonName = "volumeUp" | "volumeDown" | "power" | "actionButton" | "cameraControl";
+interface HardwareButtonsProps {
+    frameContainerRef: RefObject<HTMLDivElement | null>;
+    onButtonPress?: (button: ButtonName) => void;
+    enabled?: boolean;
+    orientation?: "portrait" | "landscape";
+}
+declare function HardwareButtons({ frameContainerRef, onButtonPress, enabled, orientation, }: HardwareButtonsProps): ReactElement | null;
+
+interface DynamicStatusBarProps {
+    contract: DeviceLayoutContract;
+    orientation: "portrait" | "landscape";
+    colorScheme: "light" | "dark";
+    showLiveClock?: boolean;
+    fixedTime?: string;
+}
+declare function DynamicStatusBar({ contract, orientation, colorScheme, showLiveClock, fixedTime, }: DynamicStatusBarProps): react.JSX.Element | null;
+
+interface StatusBarIndicatorsProps {
+    platform: "ios" | "android";
+    colorScheme: "light" | "dark";
+}
+declare function StatusBarIndicators({ platform, colorScheme }: StatusBarIndicatorsProps): react.JSX.Element;
+
+interface SVGOverrideEntry {
+    deviceId: string;
+    name?: string;
+    platform?: "ios" | "android";
+    formFactor?: "tablet" | "phone" | "foldable";
+    /** Reported logical-pt screen size (independent of SVG viewBox scale). */
+    logicalScreenWidth?: number;
+    logicalScreenHeight?: number;
+    svgString: string;
+    bezelTop: number;
+    bezelBottom: number;
+    bezelLeft: number;
+    bezelRight: number;
+    screenRect?: SVGScreenRect;
+    svgStringLandscape?: string;
+    bezelTopLandscape?: number;
+    bezelBottomLandscape?: number;
+    bezelLeftLandscape?: number;
+    bezelRightLandscape?: number;
+    screenRectLandscape?: SVGScreenRect;
+    updatedAt: string;
+}
+declare class CustomSVGStore {
+    private storage;
+    constructor(storage?: Storage | null);
+    getAll(): Record<string, SVGOverrideEntry>;
+    save(entry: SVGOverrideEntry): void;
+    remove(deviceId: string): void;
+    has(deviceId: string): boolean;
+    get(deviceId: string): SVGOverrideEntry | undefined;
+    applyAll(): void;
+    private applyEntry;
+    private persist;
+}
+declare function getCustomSVGStore(): CustomSVGStore;
+
+export { type AdaptiveScaleResult, BIELA_PREFIX, type BielaColorSchemeMessage, type BielaDeviceInfoMessage, type BielaRequestMessage, type ButtonName, CustomSVGStore, DeviceCompare, type DeviceCompareProps, DeviceErrorBoundary, DeviceFrame, type DeviceFrameInfo, type DeviceFrameInsets, type DeviceFrameProps, DynamicStatusBar, type FoldState, HardwareButtons, SCALE_STEPS, type SVGCropArea, type SVGOverrideEntry, SafeAreaOverlay, SafeAreaView, ScaleBar, type ScreenPowerState, StatusBarIndicators, type UseAdaptiveScaleOptions, type UseDeviceContractResult, type UseFoldStateResult, type UseOrientationResult, VolumeHUD, type VolumeState, computeAdaptiveScale, computeFullScale, computeHostSize, getCustomSVGStore, isBielaMessage, ptsToPercent, ptsToPx, pxToPts, registerCustomDeviceSVG, registerDeviceSVG, scaleValue, snapToStep, useAdaptiveScale, useContainerSize, useDeviceContract, useDeviceFrame, useFoldState, useOrientation, useScreenPower, useVolumeControl };