@dragcraft/device-frames 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT hackycy <https://github.com/hackycy>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,518 @@
+import { LayoutPlan, StyleValueMap } from "@dragcraft/core";
+import { Component, InjectionKey, PropType, Ref, VNode } from "vue";
+//#region src/types.d.ts
+type DeviceFrameSelectionPlane = 'root' | 'content' | 'viewport';
+/** Structural counterpart of Renderer selection presentation registration. */
+interface DeviceFrameSelectionPresentationHost {
+  registerPlane: (plane: DeviceFrameSelectionPlane, element: HTMLElement | null) => void;
+}
+/**
+ * Supported device frame identifiers.
+ */
+type DeviceType = 'iphone' | 'android' | 'tablet' | 'desktop';
+/**
+ * Complete description of a device frame preset.
+ */
+interface DevicePreset {
+  /** Unique device identifier */
+  type: DeviceType;
+  /** Human-readable label for host-owned device controls. */
+  label: string;
+  /** Optional i18n key resolved by a host-provided translator. */
+  labelKey?: string;
+  /** Icon character or component for compact device buttons. */
+  icon: string | Component;
+  /** Content viewport width in CSS pixels */
+  width: number;
+  /** Content viewport height in CSS pixels */
+  height: number;
+  /** The Vue component rendering the frame chrome */
+  frameComponent: Component;
+}
+/**
+ * Reactive context provided to descendants via provide/inject.
+ * Controls which device frame is currently active.
+ */
+interface DeviceFrameContext {
+  /** Reactive device type ref — mutate this to switch devices */
+  currentDevice: Ref<DeviceType>;
+  /** All registered presets */
+  presets: readonly DevicePreset[];
+  /** Lookup a preset by type */
+  getPreset: (type: DeviceType) => DevicePreset | undefined;
+  /** Switch to a device type */
+  setDevice: (type: DeviceType) => void;
+}
+/**
+ * Injection key for the device frame context.
+ */
+declare const DEVICE_FRAME_CONTEXT_KEY: InjectionKey<DeviceFrameContext>;
+/**
+ * Options for createDeviceFrameContext.
+ */
+interface DeviceFrameOptions {
+  /** Initial device to display. Defaults to 'iphone'. */
+  initialDevice?: DeviceType;
+  /** Override or extend the default presets. */
+  presets?: DevicePreset[];
+}
+//#endregion
+//#region src/components/DeviceFrameShell.d.ts
+/**
+ * Stable container shell component for the renderer's containerShell extension.
+ *
+ * Reads the current device from DeviceFrameContext (provide/inject) and
+ * renders the corresponding frame component. Because this is a single
+ * stable component reference, RootRenderer's computed() never swaps
+ * components — only the internal render output changes reactively.
+ *
+ * Falls back to the iPhone frame if no context is provided.
+ */
+declare const DeviceFrameShell: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  regionVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  regionVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>> & Readonly<{}>, {
+  layoutPlan: LayoutPlan;
+  chromeVNodes: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[];
+  layerVNodes: Record<string, VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[]>;
+  forbiddenOverlayVNode: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }> | null;
+  surfaceStyle: StyleValueMap;
+  selectionPresentation: DeviceFrameSelectionPresentationHost;
+  regionVNodes: Record<string, VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[]>;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/components/DevicePicker.d.ts
+type Translate = (key: string, fallback?: string) => string;
+declare const _default$2: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  context: {
+    type: PropType<DeviceFrameContext>;
+    required: true;
+  };
+  translate: {
+    type: PropType<Translate>;
+    default: undefined;
+  };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  context: {
+    type: PropType<DeviceFrameContext>;
+    required: true;
+  };
+  translate: {
+    type: PropType<Translate>;
+    default: undefined;
+  };
+}>> & Readonly<{}>, {
+  translate: Translate;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/components/frames/AndroidFrame.d.ts
+/**
+ * Android phone frame with status bar and bottom navigation bar.
+ * Renders children via the default slot inside the content area.
+ */
+declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>> & Readonly<{}>, {
+  layoutPlan: LayoutPlan;
+  chromeVNodes: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[];
+  layerVNodes: Record<string, VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[]>;
+  forbiddenOverlayVNode: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }> | null;
+  surfaceStyle: StyleValueMap;
+  selectionPresentation: DeviceFrameSelectionPresentationHost;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/components/frames/DesktopFrame.d.ts
+/**
+ * Desktop browser chrome frame with title bar, traffic lights, and URL bar.
+ * Renders children via the default slot inside the content area.
+ */
+declare const _default$1: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>> & Readonly<{}>, {
+  layoutPlan: LayoutPlan;
+  chromeVNodes: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[];
+  layerVNodes: Record<string, VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[]>;
+  forbiddenOverlayVNode: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }> | null;
+  surfaceStyle: StyleValueMap;
+  selectionPresentation: DeviceFrameSelectionPresentationHost;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/components/frames/IPhoneFrame.d.ts
+/**
+ * iPhone frame with Dynamic Island notch, status bar, and home indicator.
+ * Status bar uses a 3-column grid layout: time (left) | Dynamic Island (center) | icons (right),
+ * matching the real iPhone status bar layout.
+ * Renders children via the default slot inside the content area.
+ */
+declare const _default$3: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>> & Readonly<{}>, {
+  layoutPlan: LayoutPlan;
+  chromeVNodes: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[];
+  layerVNodes: Record<string, VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[]>;
+  forbiddenOverlayVNode: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }> | null;
+  surfaceStyle: StyleValueMap;
+  selectionPresentation: DeviceFrameSelectionPresentationHost;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/components/frames/TabletFrame.d.ts
+/**
+ * Tablet / iPad frame with minimal chrome and thin bezels.
+ * Renders children via the default slot inside the content area.
+ */
+declare const _default$4: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>, () => VNode<import("vue").RendererNode, import("vue").RendererElement, {
+  [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+  layoutPlan: {
+    type: PropType<LayoutPlan>;
+    default: undefined;
+  };
+  chromeVNodes: {
+    type: PropType<VNode[]>;
+    default: () => never[];
+  };
+  layerVNodes: {
+    type: PropType<Record<string, VNode[]>>;
+    default: () => {};
+  };
+  forbiddenOverlayVNode: {
+    type: PropType<VNode | null>;
+    default: null;
+  };
+  surfaceStyle: {
+    type: PropType<StyleValueMap>;
+    default: undefined;
+  };
+  selectionPresentation: {
+    type: PropType<DeviceFrameSelectionPresentationHost>;
+    default: undefined;
+  };
+}>> & Readonly<{}>, {
+  layoutPlan: LayoutPlan;
+  chromeVNodes: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[];
+  layerVNodes: Record<string, VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>[]>;
+  forbiddenOverlayVNode: VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }> | null;
+  surfaceStyle: StyleValueMap;
+  selectionPresentation: DeviceFrameSelectionPresentationHost;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+//#endregion
+//#region src/composables/useDeviceFrame.d.ts
+/**
+ * Convenience composable for consuming device frame state in any descendant.
+ * Returns the full context plus commonly needed computed values.
+ *
+ * @example
+ * ```ts
+ * const { currentDevice, setDevice, presets } = useDeviceFrame()
+ * ```
+ */
+declare function useDeviceFrame(): {
+  /** Reactive current device type */
+  currentDevice: import("vue").Ref<DeviceType, DeviceType>;
+  /** Reactive current preset object */
+  currentPreset: import("vue").ComputedRef<DevicePreset | undefined>;
+  /** Reactive viewport width */
+  viewportWidth: import("vue").ComputedRef<number>;
+  /** Reactive viewport height */
+  viewportHeight: import("vue").ComputedRef<number>;
+  /** All available presets */
+  presets: readonly DevicePreset[];
+  /** Switch device */
+  setDevice: (type: DeviceType) => void;
+};
+//#endregion
+//#region src/context.d.ts
+/**
+ * Creates a DeviceFrameContext. The caller is responsible for calling
+ * `provide(DEVICE_FRAME_CONTEXT_KEY, ctx)` in their setup().
+ *
+ * @example
+ * ```ts
+ * const ctx = createDeviceFrameContext({ initialDevice: 'iphone' })
+ * provide(DEVICE_FRAME_CONTEXT_KEY, ctx)
+ * ```
+ */
+declare function createDeviceFrameContext(options?: DeviceFrameOptions): DeviceFrameContext;
+/**
+ * Injects the DeviceFrameContext from the nearest ancestor provider.
+ * Throws if not found.
+ */
+declare function useDeviceFrameContext(): DeviceFrameContext;
+//#endregion
+//#region src/presets.d.ts
+declare const IPHONE_PRESET: DevicePreset;
+declare const ANDROID_PRESET: DevicePreset;
+declare const TABLET_PRESET: DevicePreset;
+declare const DESKTOP_PRESET: DevicePreset;
+/**
+ * Returns the built-in device presets: iPhone, Android, Tablet, Desktop.
+ */
+declare function getDefaultPresets(): DevicePreset[];
+//#endregion
+export { ANDROID_PRESET, _default as AndroidFrame, DESKTOP_PRESET, DEVICE_FRAME_CONTEXT_KEY, _default$1 as DesktopFrame, type DeviceFrameContext, type DeviceFrameOptions, type DeviceFrameSelectionPlane, type DeviceFrameSelectionPresentationHost, DeviceFrameShell, _default$2 as DevicePicker, type DevicePreset, type DeviceType, IPHONE_PRESET, _default$3 as IPhoneFrame, TABLET_PRESET, _default$4 as TabletFrame, createDeviceFrameContext, getDefaultPresets, useDeviceFrame, useDeviceFrameContext };