react-display-scale-engine 0.1.1

package/dist/displayScaleLogicalViewport-Ikf-DtkQ.d.ts

@@ -0,0 +1,159 @@
+/** How browser zoom was estimated. */
+type DisplayScaleDetectionMethod = "visual-viewport" | "baseline-ratio" | "device-pixel-ratio" | "unavailable";
+type DisplayScaleConfidence = "high" | "medium" | "low";
+/** Whether browser-zoom calibration was explicitly confirmed by the application. */
+type DisplayScaleCalibration = "explicit" | "automatic" | "unavailable";
+type DisplayScaleViewport = {
+    width: number;
+    height: number;
+};
+type DisplayScaleScreen = {
+    width: number;
+    height: number;
+    availWidth: number;
+    availHeight: number;
+};
+/**
+ * Point-in-time reading of display / zoom state.
+ *
+ * - `browserZoom`: page zoom relative to the calibrated baseline (1 = 100%).
+ * - `osDisplayScale`: OS display scaling (DPI) estimated from DPR ÷ browser zoom.
+ * - `devicePixelRatio`: raw `window.devicePixelRatio`.
+ */
+type DisplayScaleSnapshot = {
+    browserZoom: number;
+    browserZoomPercent: number;
+    osDisplayScale: number;
+    osDisplayScalePercent: number;
+    devicePixelRatio: number;
+    effectiveScale: number;
+    viewport: DisplayScaleViewport;
+    screen: DisplayScaleScreen;
+    method: DisplayScaleDetectionMethod;
+    confidence: DisplayScaleConfidence;
+    calibration: DisplayScaleCalibration;
+    measuredAt: string;
+};
+type DisplayScaleBaseline = {
+    devicePixelRatio: number;
+    browserZoom: number;
+    capturedAt: string;
+    /** True only when created by recalibrateDisplayScale at a known page zoom. */
+    isExplicit?: boolean;
+};
+type DisplayScaleIssue = "browser-zoomed-in" | "browser-zoomed-out" | "high-os-scale" | "viewport-too-narrow";
+type DisplayScaleThresholds = {
+    /** Minimum acceptable browser zoom (default 0.9). */
+    browserZoomMin?: number;
+    /** Maximum acceptable browser zoom (default 1.1). */
+    browserZoomMax?: number;
+    /** Maximum acceptable OS display scale (default 2). */
+    osDisplayScaleMax?: number;
+    /** Warn when viewport width is below this CSS pixel value (default 0 = disabled). */
+    minViewportWidth?: number;
+};
+type DisplayScaleEvaluation = {
+    snapshot: DisplayScaleSnapshot;
+    issues: DisplayScaleIssue[];
+    isAcceptable: boolean;
+};
+type DetectDisplayScaleOptions = {
+    /**
+     * When no baseline exists, store the current reading as 100% browser zoom.
+     * Users can call `recalibrateDisplayScale()` after resetting browser zoom.
+     * @default true
+     */
+    autoBaseline?: boolean;
+};
+type SubscribeDisplayScaleOptions = DetectDisplayScaleOptions & {
+    /** Debounce window resize / visualViewport events. @default 100 */
+    debounceMs?: number;
+};
+
+type DisplayScaleCompensationConfig = {
+    /** Master switch. @default true */
+    enabled: boolean;
+    /** Only run on Windows desktop/laptop — skips macOS Retina (DPR 2). @default true */
+    windowsOnly: boolean;
+    /** Compensate when snapped OS scale is above this value. @default 1.05 */
+    minOsScaleToCompensate: number;
+    /** Emulate this OS scale after compensation (1 = 100%). @default 1 */
+    targetOsScale: number;
+    /** Snap measured scale to Windows tiers for stable zoom. @default true */
+    snapOsScale: boolean;
+    /** Require a baseline explicitly calibrated at known browser zoom before compensating. @default false */
+    requireExplicitCalibration: boolean;
+};
+declare const DEFAULT_DISPLAY_SCALE_COMPENSATION_CONFIG: DisplayScaleCompensationConfig;
+type DisplayScaleCompensation = {
+    active: boolean;
+    /** CSS `zoom` / transform scale applied to the app root (e.g. 0.667 for 150% OS). */
+    zoom: number;
+    /** @deprecated Prefer {@link measureDisplayScaleLayoutExtents} pixel layout size. */
+    widthPercent: number;
+    /** @deprecated Prefer {@link measureDisplayScaleLayoutExtents} pixel layout size. */
+    heightPercent: number;
+    /** Snapped OS scale used for compensation. */
+    osDisplayScale: number;
+    /** Target OS scale after compensation (percent). */
+    targetOsScalePercent: number;
+};
+type DisplayScaleLayoutExtents = {
+    /** Pre-zoom layout width so `layoutWidth * zoom` matches the visible viewport. */
+    layoutWidthPx: number;
+    /** Pre-zoom layout height so `layoutHeight * zoom` matches the visible viewport. */
+    layoutHeightPx: number;
+};
+type ComputeDisplayScaleCompensationOptions = Partial<DisplayScaleCompensationConfig>;
+declare function supportsCssZoom(): boolean;
+declare function computeDisplayScaleCompensation(snapshot: DisplayScaleSnapshot, options?: ComputeDisplayScaleCompensationOptions): DisplayScaleCompensation;
+/**
+ * Warm up detection before React mounts (stores baseline + sets html metadata).
+ * Visual compensation is applied by `DisplayScaleCompensationProvider`.
+ */
+declare function primeDisplayScaleCompensation(options?: ComputeDisplayScaleCompensationOptions): DisplayScaleCompensation;
+/** Read the visible viewport in CSS pixels (avoids `%` / `vw` inflation on scaled displays). */
+declare function readDisplayScaleViewportSize(): {
+    width: number;
+    height: number;
+};
+/** Layout box size for the compensation root before `zoom` is applied. */
+declare function measureDisplayScaleLayoutExtents(zoom: number): DisplayScaleLayoutExtents;
+declare function applyDisplayScaleCompensationStyles(element: HTMLElement, compensation: DisplayScaleCompensation, extents?: DisplayScaleLayoutExtents): void;
+declare function clearDisplayScaleCompensationStyles(element: HTMLElement): void;
+/** Publish compensation metadata on `html` (visual zoom lives on the app root). */
+declare function syncDisplayScaleCompensationMetadata(compensation: DisplayScaleCompensation, extents?: DisplayScaleLayoutExtents, snapshot?: DisplayScaleSnapshot): void;
+/** @deprecated Use {@link syncDisplayScaleCompensationMetadata} + root element styles. */
+declare function applyDisplayScaleCompensationToDocument(compensation: DisplayScaleCompensation): void;
+/** Remove html metadata from legacy document-level compensation. */
+declare function clearDisplayScaleCompensationFromDocument(): void;
+
+type DisplayScaleLogicalViewport = {
+    /** Visible viewport in browser CSS pixels. */
+    viewportWidth: number;
+    viewportHeight: number;
+    /** Visible viewport in the compensated root's coordinate space. */
+    logicalWidth: number;
+    logicalHeight: number;
+    zoom: number;
+};
+type DisplayScaleOverlayBoundsOptions = {
+    /** Space between the anchor and the overlay, in visible CSS pixels. */
+    offset?: number;
+    /** Minimum safe space at the viewport edge, in visible CSS pixels. */
+    viewportInset?: number;
+};
+/**
+ * Returns viewport dimensions in both browser and compensated-root coordinates.
+ * Use the logical dimensions for content that is rendered inside the compensated root.
+ */
+declare function getDisplayScaleLogicalViewport(compensation: Pick<DisplayScaleCompensation, "zoom">): DisplayScaleLogicalViewport;
+/** Convert a visible browser CSS-pixel measurement to the compensated root coordinate space. */
+declare function toDisplayScaleLogicalPixels(value: number, compensation: Pick<DisplayScaleCompensation, "zoom">): number;
+/**
+ * Maximum height for an overlay positioned below an anchor.
+ * The return value is suitable for an element rendered in the compensated root.
+ */
+declare function getDisplayScaleOverlayMaxHeight(anchorRect: Pick<DOMRect, "bottom">, compensation: Pick<DisplayScaleCompensation, "zoom">, options?: DisplayScaleOverlayBoundsOptions): number;
+
+export { supportsCssZoom as A, syncDisplayScaleCompensationMetadata as B, type ComputeDisplayScaleCompensationOptions as C, DEFAULT_DISPLAY_SCALE_COMPENSATION_CONFIG as D, toDisplayScaleLogicalPixels as E, type SubscribeDisplayScaleOptions as S, type DetectDisplayScaleOptions as a, type DisplayScaleBaseline as b, type DisplayScaleCalibration as c, type DisplayScaleCompensation as d, type DisplayScaleCompensationConfig as e, type DisplayScaleConfidence as f, type DisplayScaleDetectionMethod as g, type DisplayScaleEvaluation as h, type DisplayScaleIssue as i, type DisplayScaleLayoutExtents as j, type DisplayScaleLogicalViewport as k, type DisplayScaleOverlayBoundsOptions as l, type DisplayScaleScreen as m, type DisplayScaleSnapshot as n, type DisplayScaleThresholds as o, type DisplayScaleViewport as p, applyDisplayScaleCompensationStyles as q, applyDisplayScaleCompensationToDocument as r, clearDisplayScaleCompensationFromDocument as s, clearDisplayScaleCompensationStyles as t, computeDisplayScaleCompensation as u, getDisplayScaleLogicalViewport as v, getDisplayScaleOverlayMaxHeight as w, measureDisplayScaleLayoutExtents as x, primeDisplayScaleCompensation as y, readDisplayScaleViewportSize as z };

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_DISPLAY_SCALE_THRESHOLDS, clearDisplayScaleBaseline, detectDisplayScale, evaluateDisplayScale, readDisplayScaleBaseline, recalibrateDisplayScale, resetDisplayScaleEngine, shouldApplyOsScaleCompensation, snapToWindowsOsScale, subscribeDisplayScale, writeDisplayScaleBaseline } from './core.js';
+export { C as ComputeDisplayScaleCompensationOptions, D as DEFAULT_DISPLAY_SCALE_COMPENSATION_CONFIG, a as DetectDisplayScaleOptions, b as DisplayScaleBaseline, c as DisplayScaleCalibration, d as DisplayScaleCompensation, e as DisplayScaleCompensationConfig, f as DisplayScaleConfidence, g as DisplayScaleDetectionMethod, h as DisplayScaleEvaluation, i as DisplayScaleIssue, j as DisplayScaleLayoutExtents, k as DisplayScaleLogicalViewport, l as DisplayScaleOverlayBoundsOptions, m as DisplayScaleScreen, n as DisplayScaleSnapshot, o as DisplayScaleThresholds, p as DisplayScaleViewport, S as SubscribeDisplayScaleOptions, q as applyDisplayScaleCompensationStyles, r as applyDisplayScaleCompensationToDocument, s as clearDisplayScaleCompensationFromDocument, t as clearDisplayScaleCompensationStyles, u as computeDisplayScaleCompensation, v as getDisplayScaleLogicalViewport, w as getDisplayScaleOverlayMaxHeight, x as measureDisplayScaleLayoutExtents, y as primeDisplayScaleCompensation, z as readDisplayScaleViewportSize, A as supportsCssZoom, B as syncDisplayScaleCompensationMetadata, E as toDisplayScaleLogicalPixels } from './displayScaleLogicalViewport-Ikf-DtkQ.js';
+export { DisplayScaleCompensationProvider, DisplayScaleOverlay, DisplayScaleOverlayStrategy, DisplayScaleProvider, DisplayScaleProviderProps, DisplayScaleVirtualAnchor, useDisplayScale, useDisplayScaleAnchor, useDisplayScaleCompensation, useDisplayScaleOverlay, useDisplayScalePortalContainer, useLogicalMaxWidth, useLogicalMinWidth } from './react.js';
+export { DisplayScaleMenu, DisplayScaleMenuProps, DisplayScalePopover, DisplayScalePopoverProps, DisplayScalePopper, DisplayScalePopperProps, DisplayScaleSelect, createMuiDisplayScaleComponents, displayScalePageFillSx, signinSplitColumnSx, signinViewportShellSx, useDisplayScalePopoverPosition, useDisplayScaleTabsIndicator } from './mui.js';
+import 'react';
+import '@mui/material/styles';
+import '@mui/material';

package/dist/index.js

@@ -0,0 +1,8 @@
+import './chunk-SLNYXBHU.js';
+export { useDisplayScaleOverlay, useLogicalMaxWidth, useLogicalMinWidth } from './chunk-6UB65SJB.js';
+export { getDisplayScaleLogicalViewport, getDisplayScaleOverlayMaxHeight, toDisplayScaleLogicalPixels } from './chunk-U3ZWHUJG.js';
+export { DisplayScaleMenu, DisplayScalePopover, DisplayScalePopper, DisplayScaleSelect, createMuiDisplayScaleComponents, displayScalePageFillSx, signinSplitColumnSx, signinViewportShellSx, useDisplayScalePopoverPosition, useDisplayScaleTabsIndicator } from './chunk-AGM7V7PR.js';
+export { DisplayScaleCompensationProvider, DisplayScaleProvider, useDisplayScale, useDisplayScaleAnchor, useDisplayScaleCompensation, useDisplayScalePortalContainer } from './chunk-R5CTLLUS.js';
+export { DEFAULT_DISPLAY_SCALE_COMPENSATION_CONFIG, DEFAULT_DISPLAY_SCALE_THRESHOLDS, applyDisplayScaleCompensationStyles, applyDisplayScaleCompensationToDocument, clearDisplayScaleBaseline, clearDisplayScaleCompensationFromDocument, clearDisplayScaleCompensationStyles, computeDisplayScaleCompensation, detectDisplayScale, evaluateDisplayScale, measureDisplayScaleLayoutExtents, primeDisplayScaleCompensation, readDisplayScaleBaseline, readDisplayScaleViewportSize, recalibrateDisplayScale, resetDisplayScaleEngine, shouldApplyOsScaleCompensation, snapToWindowsOsScale, subscribeDisplayScale, supportsCssZoom, syncDisplayScaleCompensationMetadata, writeDisplayScaleBaseline } from './chunk-VWJNHWMD.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/mui.d.ts

@@ -0,0 +1,72 @@
+import { Components, Theme, SxProps } from '@mui/material/styles';
+import { MenuProps, PopoverProps, PopperProps, SelectProps } from '@mui/material';
+import { ReactElement, RefObject } from 'react';
+
+type PortalContainerGetter = () => HTMLElement;
+type MuiDisplayScaleComponentsOptions = {
+    getPortalContainer: PortalContainerGetter;
+    /**
+     * Overlay content is portalled outside the zoomed app root, so it needs the
+     * same density correction independently.
+     */
+    overlayZoom?: number;
+};
+/**
+ * MUI adapter for a compensated app root.
+ *
+ * Centralizing these defaults gives every MUI overlay the portal strategy and
+ * density correction chosen by the display-scale engine.
+ */
+declare function createMuiDisplayScaleComponents({ getPortalContainer, overlayZoom, }: MuiDisplayScaleComponentsOptions): Components<Theme>;
+
+type NativeAnchorProps = {
+    anchorEl?: HTMLElement | null;
+};
+type DisplayScaleMenuProps = Omit<MenuProps, "anchorEl"> & NativeAnchorProps;
+/** MUI Menu with an anchor adapted to the active portal strategy. */
+declare function DisplayScaleMenu({ anchorEl, ...props }: DisplayScaleMenuProps): ReactElement;
+type DisplayScalePopoverProps = Omit<PopoverProps, "anchorEl"> & NativeAnchorProps;
+/** MUI Popover with an anchor adapted to the active portal strategy. */
+declare function DisplayScalePopover({ anchorEl, ...props }: DisplayScalePopoverProps): ReactElement;
+type DisplayScalePopperProps = Omit<PopperProps, "anchorEl"> & NativeAnchorProps;
+/** MUI Popper with an anchor adapted to the active portal strategy. */
+declare function DisplayScalePopper({ anchorEl, ...props }: DisplayScalePopperProps): ReactElement;
+
+/**
+ * MUI Select adapter for the display-scale engine. Select creates its Menu
+ * internally, so it cannot use DisplayScaleMenu directly.
+ */
+declare function DisplayScaleSelect<Value = unknown>(props: SelectProps<Value>): ReactElement;
+
+type DisplayScalePopoverPositionOptions = {
+    open: boolean;
+    overlayRootRef: RefObject<HTMLDivElement | null>;
+    anchorElement: HTMLElement | null;
+    anchorReference?: PopoverProps["anchorReference"];
+    anchorPosition?: PopoverProps["anchorPosition"];
+    anchorOrigin?: PopoverProps["anchorOrigin"];
+    transformOrigin?: PopoverProps["transformOrigin"];
+    marginThreshold?: PopoverProps["marginThreshold"];
+};
+/**
+ * Replaces only MUI Popover's physical-viewport collision pass. MUI still
+ * owns focus, transition and anchor semantics; this writes the final logical
+ * top/left inside the compensated portal root.
+ */
+declare function useDisplayScalePopoverPosition({ open, overlayRootRef, anchorElement, anchorReference, anchorPosition, anchorOrigin, transformOrigin, marginThreshold, }: DisplayScalePopoverPositionOptions): void;
+
+/**
+ * Keeps MUI Tabs' indicator in the compensated root's logical coordinate
+ * space. MUI normally uses getBoundingClientRect(), whose values are already
+ * zoomed and therefore too small for a logical layout container.
+ */
+declare function useDisplayScaleTabsIndicator(tabsRef: RefObject<HTMLDivElement | null>, value: unknown): void;
+
+/** Fill the compensated app tree — prefer over raw `100vh` inside `#root`. */
+declare const displayScalePageFillSx: SxProps<Theme>;
+/** Full-viewport auth split layout — fills the compensated app root (not `position: fixed`). */
+declare const signinViewportShellSx: SxProps<Theme>;
+/** 50/50 desktop columns — avoids flex min-content overflow at OS display scale. */
+declare const signinSplitColumnSx: SxProps<Theme>;
+
+export { DisplayScaleMenu, type DisplayScaleMenuProps, DisplayScalePopover, type DisplayScalePopoverProps, DisplayScalePopper, type DisplayScalePopperProps, DisplayScaleSelect, createMuiDisplayScaleComponents, displayScalePageFillSx, signinSplitColumnSx, signinViewportShellSx, useDisplayScalePopoverPosition, useDisplayScaleTabsIndicator };

package/dist/mui.js

@@ -0,0 +1,5 @@
+export { DisplayScaleMenu, DisplayScalePopover, DisplayScalePopper, DisplayScaleSelect, createMuiDisplayScaleComponents, displayScalePageFillSx, signinSplitColumnSx, signinViewportShellSx, useDisplayScalePopoverPosition, useDisplayScaleTabsIndicator } from './chunk-AGM7V7PR.js';
+import './chunk-R5CTLLUS.js';
+import './chunk-VWJNHWMD.js';
+//# sourceMappingURL=mui.js.map
+//# sourceMappingURL=mui.js.map

package/dist/mui.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"mui.js"}

package/dist/react.d.ts

@@ -0,0 +1,81 @@
+import { PropsWithChildren, ReactElement, RefObject } from 'react';
+import { C as ComputeDisplayScaleCompensationOptions, d as DisplayScaleCompensation, j as DisplayScaleLayoutExtents, a as DetectDisplayScaleOptions, S as SubscribeDisplayScaleOptions, n as DisplayScaleSnapshot, o as DisplayScaleThresholds, h as DisplayScaleEvaluation, v as getDisplayScaleLogicalViewport, l as DisplayScaleOverlayBoundsOptions } from './displayScaleLogicalViewport-Ikf-DtkQ.js';
+
+type DisplayScaleCompensationContextValue = {
+    rootRef: RefObject<HTMLDivElement | null>;
+    compensation: DisplayScaleCompensation;
+    layoutExtents: DisplayScaleLayoutExtents | null;
+    overlayStrategy: DisplayScaleOverlayStrategy;
+};
+type DisplayScaleOverlayStrategy = "compensated-root" | "document-body";
+type DisplayScaleProviderProps = PropsWithChildren & {
+    /**
+     * Visual-density policy for this app. The default keeps the existing
+     * Windows-to-100% compensation behavior.
+     */
+    config?: ComputeDisplayScaleCompensationOptions;
+    /**
+     * Where overlay portals render. document-body keeps MUI anchor coordinates in
+     * browser-visible pixels; this is the preferred strategy for CSS zoom roots.
+     */
+    overlayStrategy?: DisplayScaleOverlayStrategy;
+};
+declare function DisplayScaleCompensationProvider({ children, config, overlayStrategy, }: DisplayScaleProviderProps): ReactElement;
+/** Package-friendly name for the display-scale root provider. */
+declare const DisplayScaleProvider: typeof DisplayScaleCompensationProvider;
+declare function useDisplayScaleCompensation(): DisplayScaleCompensationContextValue;
+/**
+ * Portal target selected by the display-scale strategy.
+ *
+ * `document-body` is the default because it shares browser-visible coordinates
+ * with a native anchor; the MUI theme adapter corrects the overlay density.
+ */
+declare function useDisplayScalePortalContainer(): HTMLElement | null;
+
+type UseDisplayScaleOptions = DetectDisplayScaleOptions & Pick<SubscribeDisplayScaleOptions, "debounceMs">;
+type UseDisplayScaleResult = {
+    snapshot: DisplayScaleSnapshot;
+    evaluate: (thresholds?: DisplayScaleThresholds) => DisplayScaleEvaluation;
+};
+/**
+ * React hook — reactive display zoom / scale readings for UI guards or telemetry.
+ */
+declare function useDisplayScale(options?: UseDisplayScaleOptions): UseDisplayScaleResult;
+
+type DisplayScaleVirtualAnchor = {
+    contextElement: HTMLElement;
+    getBoundingClientRect: () => DOMRect;
+    nodeType: 1;
+};
+/**
+ * Converts an anchor rectangle from visible browser pixels to the coordinate
+ * space of the compensated engine root. The return value is accepted by MUI
+ * Menu, Popover and Popper as a virtual anchor.
+ */
+declare function useDisplayScaleAnchor(anchorElement: HTMLElement | null): HTMLElement | DisplayScaleVirtualAnchor | null;
+
+type DisplayScaleOverlay = {
+    /** MUI portal target selected by the engine strategy. */
+    portalContainer: HTMLElement | null;
+    logicalViewport: ReturnType<typeof getDisplayScaleLogicalViewport>;
+    toLogicalPixels: (value: number) => number;
+    /** Converts a visible size to the CSS size required by density-zoomed content. */
+    toOverlayContentPixels: (value: number) => number;
+    getMaxHeightBelowAnchor: (anchor: HTMLElement, options?: DisplayScaleOverlayBoundsOptions) => number;
+};
+/**
+ * Overlay geometry adapter. Use this instead of dividing coordinates by the
+ * display-scale zoom in feature code.
+ */
+declare function useDisplayScaleOverlay(): DisplayScaleOverlay;
+
+/**
+ * Tests a breakpoint against the compensated root width rather than the raw
+ * browser viewport. Use for app-shell decisions that must preserve the same
+ * layout at Windows 100% and compensated 150%.
+ */
+declare function useLogicalMinWidth(minWidth: number): boolean;
+/** Logical counterpart to a max-width media query. */
+declare function useLogicalMaxWidth(maxWidth: number): boolean;
+
+export { DisplayScaleCompensationProvider, type DisplayScaleOverlay, type DisplayScaleOverlayStrategy, DisplayScaleProvider, type DisplayScaleProviderProps, type DisplayScaleVirtualAnchor, useDisplayScale, useDisplayScaleAnchor, useDisplayScaleCompensation, useDisplayScaleOverlay, useDisplayScalePortalContainer, useLogicalMaxWidth, useLogicalMinWidth };

package/dist/react.js

@@ -0,0 +1,6 @@
+export { useDisplayScaleOverlay, useLogicalMaxWidth, useLogicalMinWidth } from './chunk-6UB65SJB.js';
+import './chunk-U3ZWHUJG.js';
+export { DisplayScaleCompensationProvider, DisplayScaleProvider, useDisplayScale, useDisplayScaleAnchor, useDisplayScaleCompensation, useDisplayScalePortalContainer } from './chunk-R5CTLLUS.js';
+import './chunk-VWJNHWMD.js';
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"react.js"}

package/docs/display-scale-engine.md

@@ -0,0 +1,208 @@
+# Display-scale engine
+
+## Purpose
+
+The display-scale engine provides an optional **visual-density lock** for Windows desktop browsers.
+When Windows display scale is 125%, 150%, or another supported tier, the app can render toward a
+100% visual-density target while retaining an expanded logical layout area.
+
+This is a product policy, not a browser requirement. A conventional responsive website should not
+enable this behavior unless matching 100% visual density is an explicit requirement.
+
+## Scope and limitations
+
+- The engine targets Windows desktop and is disabled for coarse-pointer and compact viewports.
+- Browser page zoom and OS display scale are not perfectly distinguishable in a normal browser.
+  `window.devicePixelRatio` is an effective value influenced by both.
+- The session baseline assumes browser page zoom is 100% when first stored. If this is not true,
+  call `recalibrateDisplayScale()` after the user resets page zoom to 100%.
+- Native shells such as Electron can provide a more authoritative OS scale factor. A pure web app
+  cannot.
+
+## Architecture
+
+```text
+display-scale core
+  detection + calibration + compensation policy
+              |
+              v
+React provider
+  compensated root (visible portal host) + logical viewport context
+              |
+              +-- clipped app-content layer
+              +-- document-body MUI portal host
+              +-- overlay adapter
+```
+
+The code is intentionally divided so that the core calculation modules do not depend on React or
+MUI. The React-facing API is exported from `@/shared/display-scale` today and can be moved into
+an internal package without changing feature call sites.
+
+## Public API
+
+```tsx
+import {
+  DisplayScaleProvider,
+  useDisplayScale,
+  useDisplayScaleOverlay,
+} from "@/shared/display-scale";
+
+<DisplayScaleProvider
+  config={{
+    windowsOnly: true,
+    targetOsScale: 1,
+    minOsScaleToCompensate: 1.05,
+    requireExplicitCalibration: true,
+  }}
+>
+  <App />
+</DisplayScaleProvider>;
+```
+
+### Core utilities
+
+- `detectDisplayScale()`: returns current DPR, estimated OS scale, estimated browser zoom and
+  confidence.
+- `recalibrateDisplayScale()`: replaces the current session baseline when browser zoom is known
+  to be 100% and marks it as explicit calibration.
+- `computeDisplayScaleCompensation()`: resolves whether compensation is active and the target
+  root zoom.
+- `getDisplayScaleLogicalViewport()`: returns browser viewport and compensated-root viewport.
+- `toDisplayScaleLogicalPixels()`: converts visible CSS-pixel geometry to root coordinates.
+
+### React utilities
+
+- `DisplayScaleProvider`: package-friendly name for the existing root provider.
+- `useDisplayScale()`: subscribes to a scale snapshot.
+- `useDisplayScaleCompensation()`: exposes the root and resolved compensation.
+- `useDisplayScaleOverlay()`: obtains the portal container, logical viewport and overlay bounds
+  helpers, including `toOverlayContentPixels()` for a custom density-zoomed dimension.
+- `useDisplayScaleAnchor()`: converts a native anchor to a MUI-compatible virtual anchor in the
+  compensated portal coordinate space.
+- `useLogicalMinWidth()` / `useLogicalMaxWidth()`: evaluate app-shell breakpoints against the
+  compensated root width.
+- `createMuiDisplayScaleComponents()`: optional MUI adapter that centralizes portal defaults for
+  Dialog, Menu/Popover and Popper.
+
+## Overlay integration
+
+MUI overlays must share the same coordinate system as their anchor. The theme adapter keeps legacy
+MUI portals on `document.body` with density correction. For anchored `Menu`, `Popover` and
+`Popper`, use the provided wrappers: they move only that overlay into the compensated root and
+adapt the anchor rectangle relative to the engine root centrally. This avoids the `top`/`left`
+drift caused by applying CSS zoom to an absolutely positioned body portal. The adapter also handles temporary MUI Drawers: the
+portal host, density zoom, and inverse viewport dimension are set globally. Permanent and
+persistent Drawers remain inside the compensated root and are deliberately untouched.
+
+The compensated root is intentionally a visible portal host. The app content sits in a clipped
+child layer, so a portalled overlay is bounded by the real viewport rather than an invisible
+`overflow: hidden` root rectangle.
+
+
+Use `overlayStrategy="compensated-root"` only for an app that has verified every portal and
+anchor in logical root coordinates. `document-body` is preferred for CSS zoom roots.
+
+Do not divide a Popper or Menu height by `compensation.zoom` in feature code. Use the overlay
+adapter instead; it uses visible pixels for placement and converts only an overlay content
+dimension when its density zoom requires it:
+
+```tsx
+const { getMaxHeightBelowAnchor } = useDisplayScaleOverlay();
+
+const maxHeight = getMaxHeightBelowAnchor(anchorElement, {
+  offset: 8,
+  viewportInset: 16,
+});
+```
+
+For MUI `Menu`, `Popover` and `Popper`, adapt the anchor before passing it to the component:
+
+```tsx
+const [anchorEl, setAnchorEl] = useState<HTMLElement | null>(null);
+const displayScaleAnchor = useDisplayScaleAnchor(anchorEl);
+
+<Menu anchorEl={displayScaleAnchor} open={Boolean(anchorEl)} />;
+```
+
+For new code, prefer the MUI wrappers so the conversion cannot be skipped:
+
+```tsx
+import { DisplayScaleMenu, DisplayScalePopover, DisplayScalePopper } from "@/shared/display-scale";
+
+<DisplayScaleMenu anchorEl={anchorEl} open={Boolean(anchorEl)} />;
+```
+
+The wrappers accept a native `HTMLElement` anchor, and also support a Menu using
+`anchorReference="anchorPosition"`. Use the lower-level hook only for components that require a
+custom virtual anchor.
+
+For engine wrappers, MUI still performs its initial placement. The engine then replaces only the
+final collision clamp with a logical-viewport calculation, preserving MUI focus handling,
+transitions and origin semantics. `Popper` is intentionally separate because it uses Popper.js
+modifiers rather than MUI Popover's collision implementation.
+
+For custom positioning:
+
+1. Read the anchor rectangle with `getBoundingClientRect()`.
+2. Let `useDisplayScaleOverlay()` convert geometry only when the active portal strategy needs it.
+3. Keep the anchor, portal host and overlay in the same strategy.
+4. Give scrollable content `minHeight: 0` and put `overflowY: "auto"` on the list surface.
+5. Prefer Popper modifiers (`offset`, `flip`, `preventOverflow`) over hard-coded
+   `position: fixed`, `top` or `right`.
+
+## Responsive guidance
+
+Visual density and responsive behavior are separate:
+
+- **Density** controls perceived font, component and spacing size.
+- **Responsive behavior** controls breakpoints, columns and navigation variants.
+- **Overlay geometry** controls portals and viewport bounds.
+
+Browser-level media queries still observe the browser CSS viewport. Features that must preserve the
+same breakpoint behavior at 100% and 150% should use container queries within the compensated root
+or `useLogicalMinWidth()` / `useLogicalMaxWidth()` for JavaScript app-shell decisions. Do not
+assume root `zoom` changes `window.matchMedia()`.
+
+## Migration plan for another React app
+
+1. Copy or package only `displayScaleCompensation`, `detectDisplayScale`, baseline storage,
+   types and logical viewport utilities as the core layer.
+2. Add `DisplayScaleProvider` around the new app shell.
+3. Configure the app's portal system with `createMuiDisplayScaleComponents()`.
+4. Migrate overlays first, then fixed-position pages, then breakpoint-sensitive layouts.
+5. For strict density lock, set `requireExplicitCalibration: true` and call
+   `recalibrateDisplayScale()` after the app confirms that browser zoom is 100%.
+
+Suggested future package structure:
+
+```text
+@envidi/display-scale-core
+@envidi/display-scale-react
+@envidi/display-scale-mui
+```
+
+The MUI package should remain optional; core must not import MUI.
+
+## Verification matrix
+
+Run the following with browser page zoom at 100%, then repeat at 80%, 125% and 150%:
+
+| Windows display scale | Required result |
+| --- | --- |
+| 100% | No compensation; baseline visual layout |
+| 125% | Target visual density; no overlay clipping |
+| 150% | Target visual density; no overlay drift or viewport overflow |
+| Multiple monitors | Re-read scale after the window moves; recalibrate if confidence is insufficient |
+
+Check at minimum: app shell, sidebar animation, dialogs, menus, Popper lists, fixed controls,
+virtualized or scrollable lists, responsive grids and sign-in.
+
+## Current known work
+
+- Factory selector uses `useDisplayScaleOverlay()` for viewport-bounded list height.
+- MUI portals are globally routed to `document.body` by default; the theme adapter applies the
+  matching overlay density there, avoiding coordinate drift from the compensated root.
+- The app shell and sidebar profile already use logical breakpoints. Dashboard grids and other
+  feature-level breakpoint consumers remain a staged migration.
+- The engine currently uses best-effort browser-zoom detection; explicit calibration UX remains a
+  follow-up before enabling strict density lock across other apps.

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "react-display-scale-engine",
+  "version": "0.1.1",
+  "description": "React and Material UI utilities for consistent Windows display-scale rendering.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./mui": {
+      "types": "./dist/mui.d.ts",
+      "import": "./dist/mui.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "rds-engine": "bin/rds-engine.mjs"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "check": "npm run typecheck && npm run build",
+    "pack:check": "npm pack --dry-run",
+    "release:check": "node ./bin/rds-engine.mjs check",
+    "release:dry-run": "node ./bin/rds-engine.mjs publish --dry-run",
+    "release:publish": "node ./bin/rds-engine.mjs publish"
+  },
+  "keywords": [
+    "react",
+    "mui",
+    "material-ui",
+    "windows",
+    "display-scale",
+    "dpi",
+    "popover"
+  ],
+  "peerDependencies": {
+    "@emotion/react": ">=11.0.0",
+    "@emotion/styled": ">=11.0.0",
+    "@mui/material": ">=5.0.0",
+    "@popperjs/core": ">=2.0.0",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.0",
+    "@mui/material": "^7.3.5",
+    "@popperjs/core": "^2.11.8",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}