ng-auto-position 0.0.0 → 0.0.2

package/README.md

@@ -1,27 +1,180 @@
-# NgAutoPosition
+# **ng-auto-position**
 
-This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 17.3.7.
+A lightweight **Angular standalone directive** that automatically positions dropdowns, popovers, and floating panels relative to a reference element, while correctly handling scrolling, resizing, viewport boundaries, and scroll locking.
 
-## Development server
+This directive is designed for cases where **Angular CDK Overlay is too heavy**, but you still need **reliable, production-grade positioning**.
 
-Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
+---
 
-## Code scaffolding
+## **✨ Features**
 
-Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
+- ✅ **Smart Positioning**: Auto positions popup **above or below** a reference element.
+- ✅ **Dynamic Tracking**: Popup **follows the reference** while scrolling (no freezing).
+- ✅ **Boundary Detection**: Viewport clamping when the reference is visible.
+- ✅ **Natural Exit**: Popup moves out of viewport when the reference fully leaves.
+- ✅ **Responsive**: Optional repositioning on scroll & resize.
+- ✅ **Layout Sync**: Optional width matching with reference element.
+- ✅ **UX Control**: Optional background scroll locking and internal scroll handling.
+- ✅ **Modern**: Standalone directive (Angular 16+), no Angular CDK dependency.
 
-## Build
+---
 
-Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
+## **📦 Installation**
 
-## Running unit tests
+npm install ng-auto-position
 
-Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+---
 
-## Running end-to-end tests
+## **📌 Basic Usage**
 
-Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
+### **1\. Component Template**
 
-## Further help
+Apply the directive and provide the ID of the element it should anchor to.
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.
+HTML
+
+```html
+<div
+  class="flex flex-row"
+  style="
+    display: flex;
+    flex-direction: column;
+    position: relative;
+    left: 100vw;
+    top: 100vh;
+    height: 100vh;
+    width: 200vw;
+    padding: 700px;
+  "
+>
+  <div>Lorem ipsum, dolor sit amet consectetur adipisicing elit.</div>
+  <div style="height: fit-content">
+    <button style="padding: 4px; border: 2px solid" (click)="toggle()">Toggle</button>
+    @if (show) {
+    <div
+      ngAutoPosition
+      style="
+          width: 200px;
+          height: 200px;
+          border: 1px solid;
+          background-color: white;
+        "
+    ></div>
+    }
+  </div>
+  <div>Lorem ipsum, dolor sit amet consectetur adipisicing elit.</div>
+</div>
+```
+
+Typescript
+
+```typescript
+import { NgAutoPositionElementDirective } from "../ng-auto-position.directive";
+import { CommonModule } from "@angular/common";
+import { Component } from "@angular/core";
+
+@Component({
+  selector: "ng-auto-position-test",
+  standalone: true,
+  imports: [CommonModule, NgAutoPositionElementDirective],
+  templateUrl: "./ng-autoposition-test.component.html",
+})
+export class NgAutoPositionTestComponent {
+  show: boolean = false;
+
+  toggle() {
+    this.show = !this.show;
+  }
+}
+```
+
+---
+
+## **⚙️ API Inputs**
+
+| Input                | Type     | Default | Description                                           |
+| :------------------- | :------- | :------ | :---------------------------------------------------- |
+| referenceElementId   | string   | null    | ID of the reference element.                          |
+| enableAutoReposition | boolean  | true    | Reposition on window scroll & resize.                 |
+| debounceMs           | number   | 0       | Debounce delay for scroll/resize events.              |
+| offset               | number   | 0       | Pixel gap between reference and popup.                |
+| matchWidth           | boolean  | false   | Match popup width to reference element width.         |
+| scrollableSelector   | string   | null    | Inner element selector to limit height/enable scroll. |
+| hideScrollTargets    | string[] | null    | IDs or classes (e.g. ['body']) to hide scrollbars.    |
+
+---
+
+## **🧩 Advanced Examples**
+
+### **1\. Dropdown with internal scrolling**
+
+Automatically constrains height and enables internal scrolling if the viewport is too small.
+
+HTML
+
+```html
+<button id="actionsBtn">Actions</button>
+
+<div autoPositionElement referenceElementId="actionsBtn" scrollableSelector=".menu-items" class="dropdown">
+  <div class="menu-items"></div>
+</div>
+```
+
+CSS
+
+```css
+.menu-items {
+  overflow-y: auto;
+}
+```
+
+### **2\. Lock background scrolling**
+
+Prevents the user from scrolling the background while the popup is active.
+
+HTML
+
+```html
+<div autoPositionElement referenceElementId="menuBtn" [hideScrollTargets]="['body', '.layout-container']" class="dropdown">Menu content</div>
+```
+
+---
+
+## **🧠 Positioning Behavior Explained**
+
+- **Reference is fully visible**: Popup is clamped to the viewport to prevent overflow on all sides.
+- **Reference is partially visible**: Popup remains visible and clamped to the viewport.
+- **Reference is outside viewport**: Popup moves with the reference and can go fully off-screen. It never "freezes" or sticks in mid-air.
+
+---
+
+## **🧪 Angular Compatibility**
+
+| Angular Version | Supported |
+| :-------------- | :-------- |
+| 16+             | ✅        |
+
+### **Standalone Import Example**
+
+TypeScript
+
+```typescript
+import { AutoPositionElementDirective } from "@roshan-ng/ng-auto-position";
+
+@Component({
+  standalone: true,
+  imports: [AutoPositionElementDirective],
+})
+export class DemoComponent {}
+```
+
+---
+
+## **📄 License**
+
+MIT © Roshan
+
+## **🔗 Links**
+
+- **npm**: [https://www.npmjs.com/package/ng-auto-position](https://www.npmjs.com/package/@roshan-ng/ng-auto-position)
+- **GitHub**: [https://github.com/roshan2197/ng-auto-position](https://github.com/roshan/ng-auto-position)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ng-auto-position",
-  "version": "0.0.0",
+  "version": "0.0.2",
   "description": "Angular directive for auto positioning dropdowns and popovers",
   "dependencies": {
     "@angular/animations": "^17.3.0",
@@ -16,6 +16,42 @@
     "tslib": "^2.3.0",
     "zone.js": "~0.14.3"
   },
+  "keywords": [
+    "angular",
+    "angular-ui",
+    "angular-directive",
+    "angular-standalone",
+    "angular16",
+    "angular17",
+    "angular18",
+    "dropdown",
+    "popover",
+    "tooltip",
+    "menu",
+    "context-menu",
+    "popup",
+    "overlay",
+    "floating",
+    "floating-ui",
+    "auto-position",
+    "positioning",
+    "smart-positioning",
+    "viewport",
+    "scroll-aware",
+    "responsive-ui",
+    "cdk-alternative",
+    "no-cdk",
+    "lightweight",
+    "standalone-directive",
+    "frontend",
+    "ui",
+    "ux"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/roshan2197/ng-auto-position"
+  },
+  "homepage": "https://github.com/roshan2197/ng-auto-position",
   "module": "fesm2022/ng-auto-position.mjs",
   "typings": "index.d.ts",
   "exports": {