@a11y-ngx/overlay-base 1.0.0

package/lib/overlay-base.abstract.d.ts

@@ -0,0 +1,446 @@
+import { Subject, Observable } from 'rxjs';
+import { ViewportSize } from './overlay-base.type.private';
+import { OverlayBaseConfig, OverlayBasePosition, OverlayBaseAlignment, OverlayBasePositionStrategy, OverlayBaseCalculatedPosition, OverlayBaseSafeSpace, OverlayBaseMaxSize } from './overlay-base.type';
+export declare abstract class OverlayBase {
+    readonly uid: number;
+    readonly overlayConfig: OverlayBaseConfig;
+    private overlayMainElement;
+    triggerRect: DOMRect;
+    virtualTriggerRect: DOMRect;
+    overlayRect: DOMRect;
+    overlayOriginalRect: DOMRect;
+    boundaryRect: DOMRect;
+    isDetached$: Subject<void>;
+    private isAttached;
+    private forceUpdate$;
+    private resize$;
+    private resizeFn;
+    private scroll$;
+    private scrollFn;
+    private boundaryScroll$;
+    private boundaryScrollFn;
+    /**
+     * @description
+     * Allowed Positions & Alignments provided by the user.
+     */
+    private allowed;
+    private allowedOpposite;
+    /**
+     * @description
+     * An array of the listeners (for repositioning purposes).
+     */
+    private listeners;
+    /**
+     * @description
+     * To allow listening on page scrolling for repositioning.
+     */
+    private allowScrollListener;
+    /**
+     * @description
+     * Max `width` & `height` values allowed for the Overlay to perform
+     * proper calculations in case `fluidSize` is active.
+     */
+    readonly maxSize: OverlayBaseMaxSize;
+    /**
+     * @description
+     * Scrollbar size (`vertical` & `horizontal`) for a given custom Boundary.
+     */
+    private boundaryScrollSize;
+    /**
+     * @description
+     * The Viewport size (without the scrollbars into consideration).
+     */
+    get viewportSize(): ViewportSize;
+    /**
+     * @description
+     * The Viewport safe size.
+     * This will return width/height values taking into consideration a given custom Boundary and/or Safe Space.
+     */
+    get viewportSizeSafe(): ViewportSize;
+    private viewportSafe;
+    /**
+     * @description
+     * The chosen Position by the calculations.
+     */
+    get getCurrentPosition(): OverlayBasePosition;
+    private currentPosition;
+    private desiredPosition;
+    /**
+     * @description
+     * The chosen Alignment by the calculations.
+     */
+    get getCurrentAlignment(): OverlayBaseAlignment;
+    private currentAlignment;
+    private desiredAlignment;
+    /**
+     * @description
+     * This will provide the side of the Viewport/Boundary where the Overlay would be out of
+     * in case `fluidAlignment` is active and the Overlay, by the chosen alignment, is out of the visible area.
+     */
+    overlayOutside: OverlayBasePosition | undefined;
+    /**
+     * @description
+     * Checks that either TOP or BOTTOM positions are inside or outside the visible area.
+     *
+     * @param { number } valueTop - The numeric value for TOP position.
+     * @param { number } valueBottom - The numeric value for BOTTOM position.
+     */
+    private overlayOutsideCheckY;
+    /**
+     * @description
+     * Checks that either LEFT or RIGHT positions are inside or outside the visible area.
+     *
+     * @param { number } valueLeft - The numeric value for LEFT position.
+     * @param { number } valueRight - The numeric value for RIGHT position.
+     */
+    private overlayOutsideCheckX;
+    /**
+     * @description
+     * Boundary information such as position (top, bottom, left, right) & size (width, height).
+     */
+    private boundaryData;
+    /**
+     * @description
+     * The Trigger element to which the Overlay will be attached to.
+     */
+    get triggerElement(): HTMLElement;
+    set triggerElement(triggerElement: HTMLElement);
+    /**
+     * @description
+     * The Overlay element.
+     */
+    get overlayElement(): HTMLElement;
+    set overlayElement(overlayElement: HTMLElement);
+    /**
+     * @description
+     * Process and save the desired position & alignment.
+     */
+    private set overlayPosition(value);
+    /**
+     * @description
+     * Verifies if the given position is a valid value.
+     *
+     * @param { string } position - A given position (top, bottom, left, right).
+     * @returns { boolean }
+     */
+    private isValidPosition;
+    /**
+     * @description
+     * Verifies if the given alignment is a valid value.
+     *
+     * @param { string } alignment - A given alignment (start, center, end).
+     * @returns { boolean }
+     */
+    private isValidAlignment;
+    /**
+     * @description
+     * The position strategy to use (Fixed or Absolute).
+     */
+    get positionStrategy(): OverlayBasePositionStrategy;
+    set positionStrategy(positionStrategy: OverlayBasePositionStrategy);
+    /**
+     * @description
+     * Sets the allowed positions.
+     */
+    private set positionsAllowed(value);
+    /**
+     * @description
+     * Sets the allowed opposite positions.
+     */
+    private set oppositePositionsAllowed(value);
+    /**
+     * @description
+     * Verifies if the given position is allowed.
+     *
+     * @param { string } position - A given position (top, bottom, left, right).
+     * @returns { boolean }
+     */
+    private isPositionAllowed;
+    /**
+     * @description
+     * Sets the allowed alignments.
+     */
+    private set alignmentsAllowed(value);
+    /**
+     * @description
+     * Verifies if the given alignment is allowed.
+     *
+     * @param { string } alignment - A given alignment (start, center, end).
+     * @returns { boolean }
+     */
+    private isAlignmentAllowed;
+    private get isAlignmentStartAllowed();
+    private get isAlignmentCenterAllowed();
+    private get isAlignmentEndAllowed();
+    private get isAlignmentCenterOnly();
+    private get isDesiredAlignmentStart();
+    private get isDesiredAlignmentCenter();
+    private get isDesiredAlignmentEnd();
+    /**
+     * @description
+     * Sets a custom Boundary element.
+     *
+     * @default <body>
+     */
+    get boundaryElement(): HTMLElement;
+    set boundaryElement(boundaryElement: HTMLElement);
+    /**
+     * @description
+     * Checks if the Boundary is the `<body>` or not (custom).
+     */
+    private get isBoundaryCustom();
+    /**
+     * @description
+     * Considers an extra (safe) space for the Viewport.
+     */
+    get safeSpace(): OverlayBaseSafeSpace;
+    set safeSpace(safeSpace: OverlayBaseSafeSpace);
+    /**
+     * @description
+     * Distance between Trigger & Overlay.
+     */
+    get offsetSize(): number;
+    set offsetSize(offsetSize: number);
+    /**
+     * @description
+     * Overlay alignment is fluid, it doesn't make jumps between Start, Center or End.
+     * The Overlay will stick to the edges of the Viewport/Boundary when reaches any of them.
+     */
+    get fluidAlignment(): boolean;
+    set fluidAlignment(fluidAlignment: boolean);
+    /**
+     * @description
+     * Overlay size is fluid, it will adapt its width (for `left`/`right` positions) or
+     * height (for `top`/`bottom` positions) to the available free space.
+     *
+     * Hand in hand with this, would be good to establish `maxSize` values.
+     */
+    get fluidSize(): boolean;
+    set fluidSize(fluidSize: boolean);
+    get isTop(): boolean;
+    get isBottom(): boolean;
+    get isLeft(): boolean;
+    get isRight(): boolean;
+    get isStart(): boolean;
+    get isCenter(): boolean;
+    get isEnd(): boolean;
+    get isTopBottom(): boolean;
+    /**
+     * @description
+     * Distance between Trigger & Overlay.
+     */
+    private get triggerOverlayDistance();
+    /**
+     * @description
+     * Real Width difference between Trigger & Overlay.
+     *
+     * Positive value means the Overlay is wider than the Trigger.
+     */
+    private get triggerOverlayDifferenceWidth();
+    /**
+     * @description
+     * Real Height difference between Trigger & Overlay.
+     *
+     * Positive value means the Overlay is higher than the Trigger.
+     */
+    private get triggerOverlayDifferenceHeight();
+    /**
+     * @description
+     * Original Width difference between Trigger & Overlay.
+     *
+     * Positive value means the Overlay is wider than the Trigger.
+     */
+    private get triggerOverlayOriginalDifferenceWidth();
+    /**
+     * @description
+     * Original Height difference between Trigger & Overlay.
+     *
+     * Positive value means the Overlay is higher than the Trigger.
+     */
+    private get triggerOverlayOriginalDifferenceHeight();
+    /**
+     * @description
+     * Distance between Boundary & Viewport for the given Position.
+     *
+     * @param { OverlayBasePosition } position - A given position (top, bottom, left, right).
+     * @returns { number } The number of pixels between both elements.
+     */
+    private boundaryViewportDistance;
+    /**
+     * @description
+     * Distance between Trigger & Boundary for the given Position.
+     * This will take into consideration a given custom Boundary and/or Safe Space.
+     *
+     * @param { OverlayBasePosition } position - A given position (top, bottom, left, right).
+     * @returns { number } The number of pixels between both elements.
+     */
+    triggerBoundaryDistance(position: OverlayBasePosition): number;
+    /**
+     * @description
+     * Verifies if there is enough vertical/horizontal available space for the Overlay to fit.
+     */
+    private enoughAlignmentSpace;
+    /**
+     * @description
+     * Verifies if there is enough horizontal available space (horizontal scrolling)
+     * for the Overlay to fit.
+     */
+    private get overlayFitsHorizontally();
+    /**
+     * @description
+     * Verifies if there is enough vertical available space (vertical scrolling)
+     * for the Overlay to fit.
+     */
+    private get overlayFitsVertically();
+    /**
+     * @description
+     * Verifies if there is enough free space at the given position for the Overlay to fit.
+     *
+     * @param { OverlayBasePosition } position - A given position (top, bottom, left, right).
+     * @returns { boolean }
+     */
+    private enoughBoundarySpace;
+    /**
+     * @description
+     * Returns if the given Position is allowed and has enough space for the Overlay to fit.
+     */
+    private canPositionAt;
+    /**
+     * @description
+     * Calculates and returns the vertical alignment (for `left`/`right` positions).
+     */
+    private get getAlignmentVertically();
+    /**
+     * @description
+     * Calculates and return the horizontal alignment (for `top`/`bottom` positions).
+     */
+    private get getAlignmentHorizontally();
+    /**
+     * @description
+     * Calculates the right alignment based on the
+     *
+     * @param { number } distance - The main distance (`top` for vertical alignment, `left` for horizontal alignment).
+     * @param { boolean } canBeCentered - If the Overlay can be aligned to the center.
+     * @param { boolean } canBeStart - If the Overlay can be aligned to the start.
+     * @param { boolean } canBeEnd - If the Overlay can be aligned to the end.
+     * @returns { OverlayBaseAlignment } The alignment.
+     */
+    private getFinalAlignment;
+    /**
+     * @description
+     * Calculates maximum size (`width` or `height`) in case the overlay does not fit in the screen.
+     */
+    private get getMaxSize();
+    /**
+     * @description
+     * Returns the final Position, Alignment, Render and MaxSize.
+     */
+    private get getCalculatedPosition();
+    /**
+     * @description
+     * Returns the Overlay's `top` or `bottom` render Position/Alignment for the Strategy FIXED.
+     */
+    private get getFixedY();
+    /**
+     * @description
+     * Returns the Overlay's `left` or `right` render Position/Alignment for the Strategy FIXED.
+     */
+    private get getFixedX();
+    /**
+     * @description
+     * Returns the absolute offset distance for the given position.
+     *
+     * @param { 'left' | 'top' } position - A given position (left, top).
+     * @returns { number } The number of pixels between the chosen side and the Boundary.
+     */
+    private getAbsoluteOffset;
+    /**
+     * @description
+     * Returns the scroll distance for the given position.
+     *
+     * @param { 'left' | 'top' } position - A given position (left, top).
+     * @returns { number } The number of pixels scrolled on the chosen side for the Boundary.
+     */
+    private getAbsoluteScroll;
+    /**
+     * @description
+     * Returns the Overlay's `top` or `bottom` render Position/Alignment for the Strategy ABSOLUTE.
+     */
+    private get getAbsoluteY();
+    /**
+     * @description
+     * Returns the Overlay's `left` or `right` render Position/Alignment for the Strategy ABSOLUTE.
+     */
+    private get getAbsoluteX();
+    /**
+     * @description
+     * If the Trigger is (at least partially) outside of the Boundary on one or both of its axes
+     * and the viewport size is not big enough to fit the overlay,
+     * it'll choose the side with more available space.
+     */
+    private get getAutoPosition();
+    /**
+     * @description
+     * Returns the final position.
+     */
+    private get getPosition();
+    /**
+     * @description
+     * Returns the final alignment.
+     */
+    private get getAlignment();
+    /**
+     * @description
+     * Base listeners for Page Scroll, Page Resize, Boundary Scroll & Update on demand.
+     */
+    get overlayListeners$(): Observable<void>;
+    /**
+     * @description
+     * Update on demand to return recalculated position/alignment data.
+     */
+    recalculate(): void;
+    /**
+     * @description
+     * Update Overlay ClientRect data on demand in case its content changes.
+     *
+     * This will force recalculations.
+     */
+    updateOverlaySize(): void;
+    /**
+     * @description
+     * Sets / updates the basic config.
+     */
+    setBaseConfig(customConfig?: OverlayBaseConfig): void;
+    /**
+     * @description
+     * Assigns the provided overlay element and starts listening to the scroll & resize to calculate and return the best position for it.
+     *
+     * @param { HTMLElement } overlayElement - The `overlay` HTML element to base all calculation on.
+     * @param { number } debounceTimeMs - Delay between emissions.
+     * @returns { Observable<OverlayBaseCalculatedPosition> } An `observable` with
+     *  - the `position` (top, bottom, left, right),
+     *  - the `alignment` (start, center, end),
+     *  - the position to `render` (top, bottom, left, right) based on the chosen `position strategy` and
+     *  - the `max size` (if "`fluidSize`" is active) that'll provide max width/height so the overlay is always visible on screen.
+     */
+    attachOverlay(overlayElement: HTMLElement, debounceTimeMs?: number): Observable<OverlayBaseCalculatedPosition>;
+    /**
+     * @description
+     * Detaches the Overlay and removes the scroll listener for custom Boundary.
+     */
+    detachOverlay(): void;
+    /**
+     * @description
+     * Gets all the necessary ClientRect, Boundary and Viewport data.
+     */
+    private getElementsSizeInfo;
+    private getTriggerClientRect;
+    private getOverlayClientRect;
+    private getOverlayOriginalClientRect;
+    private getBoundaryClientRect;
+    private getBoundaryCalculatedRect;
+    private getBoundaryScrollSize;
+    private getViewportSizeSafe;
+    private getNumericValue;
+    private getBooleanValue;
+}

package/lib/overlay-base.errors.d.ts

@@ -0,0 +1 @@
+export declare const ERROR_NO_TRIGGER_PROVIDED: () => string;

package/lib/overlay-base.type.d.ts

@@ -0,0 +1,64 @@
+import { OverlayBaseRenderPosition } from './overlay-base.type.private';
+export declare enum POSITION {
+    TOP = "top",
+    BOTTOM = "bottom",
+    LEFT = "left",
+    RIGHT = "right"
+}
+export declare enum ALIGNMENT {
+    START = "start",
+    END = "end",
+    CENTER = "center"
+}
+export declare enum POSITION_STRATEGY {
+    FIXED = "fixed",
+    ABSOLUTE = "absolute"
+}
+export declare const OVERLAY_BASE_DEFAULTS: Required<Omit<OverlayBaseConfig, 'trigger' | 'boundary'>>;
+export declare type OverlayBasePosition = `${POSITION}`;
+export declare type OverlayBaseAlignment = `${ALIGNMENT}`;
+export declare type OverlayBasePositionStrategy = `${POSITION_STRATEGY}`;
+export declare type OverlayBaseSafeSpace = Partial<{
+    [key in POSITION]: number;
+}>;
+export declare type OverlayBaseMaxSize = Partial<{
+    width: number | null;
+    height: number | null;
+}>;
+export declare type OverlayBasePositionInput = OverlayBasePosition | `${POSITION}-${ALIGNMENT}` | [OverlayBasePosition, OverlayBaseAlignment];
+export declare type OverlayBasePositionsAllowed = 'auto' | 'opposite' | string | OverlayBasePosition | OverlayBasePosition[];
+export declare type OverlayBaseAlignmentsAllowed = 'auto' | 'center' | 'edges' | string | OverlayBaseAlignment | OverlayBaseAlignment[];
+export declare type OverlayBaseCalculatedPosition = {
+    /** @description Returns the position (top, bottom, left, right). */
+    position: OverlayBasePosition;
+    /** @description Returns the alignment (start, end, center). */
+    alignment: OverlayBaseAlignment;
+    /** @description Returns the numeric value to position the overlay (top, bottom, left, right). */
+    render: OverlayBaseRenderPosition;
+    /** @description Returns the maximum size (width, height). */
+    maxSize: OverlayBaseMaxSize;
+};
+export declare type OverlayBaseConfig = Partial<{
+    /** @description The trigger to which the overlay will be attached. */
+    trigger: HTMLElement | DOMRect;
+    /** @description To define a custom boundary, such as wrappers with established overflow. @default <body> */
+    boundary: HTMLElement;
+    /** @description The desired position and alignment. @default 'top-center' */
+    position: OverlayBasePositionInput;
+    /** @description Whether a `fixed` or `absolute` position will be used. @default 'fixed' */
+    positionStrategy: OverlayBasePositionStrategy;
+    /** @description To establish which positions are allowed when repositioning is needed. @default 'auto' */
+    positionsAllowed: OverlayBasePositionsAllowed;
+    /** @description To establish which alignments are allowed when repositioning is needed. @default 'auto' */
+    alignmentsAllowed: OverlayBaseAlignmentsAllowed;
+    /** @description The space between the overlay and its trigger (translated to pixels). @default 5 */
+    offsetSize: number;
+    /** @description To establish extra safe space to the viewport's edges in case some fixed areas are present. @default { top: 0, bottom: 0, left: 0, right: 0 } */
+    safeSpace: OverlayBaseSafeSpace;
+    /** @description To establish whether the overlay alignment will stick to the edges of the viewport/boundary. @default false */
+    fluidAlignment: boolean;
+    /** @description To establish whether the overlay size will adjust to the free space or stay as its original size. @default true */
+    fluidSize: boolean;
+    /** @description To allow listening for page scrolling. @default true */
+    allowScrollListener: boolean;
+}>;

package/lib/overlay-base.type.private.d.ts

@@ -0,0 +1,31 @@
+import { POSITION, OverlayBasePosition, OverlayBaseAlignment } from './overlay-base.type';
+export declare type BoundaryData = {
+    [key in POSITION]: number;
+} & {
+    width: number;
+    height: number;
+};
+export declare type OverlayBaseRenderPosition = OverlayBasePositionX & OverlayBasePositionY;
+export declare type ScrollSize = {
+    horizontal: number;
+    vertical: number;
+};
+export declare type ViewportSize = {
+    width: number;
+    height: number;
+};
+export declare type OverlayBaseAllowed = {
+    positions: OverlayBasePosition[];
+    alignments: OverlayBaseAlignment[];
+};
+export declare type OverlayBaseSquareAreas = {
+    [key in POSITION]: number;
+};
+export declare type OverlayBasePositionY = {
+    top: number | null;
+    bottom: number | null;
+};
+export declare type OverlayBasePositionX = {
+    left: number | null;
+    right: number | null;
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@a11y-ngx/overlay-base",
+  "version": "1.0.0",
+  "description": "An overlay positioning system that allows them to remain within the visible area of the viewport or a given custom boundary (such as containers with overflow) and thus prevent being out of the screen",
+  "keywords": [
+    "overlay",
+    "position",
+    "positioning",
+    "viewport",
+    "boundary",
+    "overflow",
+    "accessibility",
+    "angular"
+  ],
+  "homepage": "https://github.com/LDV2k3/a11y-libraries/tree/master/projects/a11y-ngx/overlay-base#readme",
+  "bugs": {
+    "url": "https://github.com/LDV2k3/a11y-libraries/issues",
+    "email": "lucho.development@gmail.com"
+  },
+  "license": "MPL-2.0",
+  "author": {
+    "name": "Luciano Del Vacchio",
+    "email": "lucho.development@gmail.com",
+    "url": "https://github.com/LDV2k3/"
+  },
+  "peerDependencies": {
+    "@angular/common": "^12.2.0",
+    "@angular/core": "^12.2.0"
+  },
+  "dependencies": {
+    "tslib": "^1.10.0"
+  },
+  "main": "bundles/a11y-ngx-overlay-base.umd.js",
+  "module": "fesm2015/a11y-ngx-overlay-base.js",
+  "es2015": "fesm2015/a11y-ngx-overlay-base.js",
+  "esm2015": "esm2015/a11y-ngx-overlay-base.js",
+  "fesm2015": "fesm2015/a11y-ngx-overlay-base.js",
+  "typings": "a11y-ngx-overlay-base.d.ts",
+  "sideEffects": false
+}

package/public-api.d.ts

@@ -0,0 +1,2 @@
+export * from './lib/overlay-base.abstract';
+export * from './lib/overlay-base.type';