feat: initial version

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/[email protected]/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "master",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.eslintrc.json

@@ -0,0 +1,29 @@
+{
+  "root": true,
+  "overrides": [
+    {
+      "files": [
+        "*.ts"
+      ],
+      "parserOptions": {
+        "project": [
+          "tsconfig.app.json"
+        ],
+        "createDefaultProgram": true
+      },
+      "extends": [
+        "plugin:@angular-eslint/recommended",
+        "plugin:@angular-eslint/template/process-inline-templates",
+        "@dndxdnd"
+      ]
+    },
+    {
+      "files": [
+        "*.html"
+      ],
+      "extends": [
+        "plugin:@angular-eslint/template/recommended"
+      ]
+    }
+  ]
+}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Donald Mok
+
+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.

README.md

@@ -1,27 +1,247 @@
-# EmblaCarouselAngularMonorepo
+<p align="center">
+  <a href="https://www.embla-carousel.com/"><img width="100" height="100" src="https://www.embla-carousel.com/embla-logo.svg" alt="Embla Carousel">
+  </a>
+  <a href="https://www.embla-carousel.com/"><img width="100" height="100" src="/src/assets/images/logos/angular_renaissance.png" alt="Embla Carousel">
+  </a>
+</p>
 
-This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 14.2.13.
+<h2 align="center">Embla Carousel Angular</h2>
 
-## Development server
+<p align="center">
+  An Angular wrapper for <strong>Embla Carousel</strong>.
+</p>
 
-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.
+<br>
 
-## Code scaffolding
+<h2 align="center">Installation</h2>
 
-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`.
+```shell
+npm i embla-carousel-angular
+```
 
-## Build
+<br>
 
-Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
 
-## Running unit tests
+<h2 align="center">The component structure</h2>
 
-Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
+Embla Carousel provides the handy `EmblaCarouselDirective` **standalone** directive for seamless integration with Angular. A minimal setup requires an **overflow wrapper** and a **scroll container**. Start by adding the following structure to your carousel:
 
-## Running end-to-end tests
+```ts
+import { AfterViewInit, Component, ViewChild } from '@angular/core'
+import {
+  EmblaCarouselDirective,
+  EmblaCarouselType
+} from 'embla-carousel-angular'
 
-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.
+@Component({
+  selector: 'app-carousel',
+  template: `
+    <div class="embla" emblaCarousel [options]="options">
+      <div class="embla__container">
+        <div class="embla__slide">Slide 1</div>
+        <div class="embla__slide">Slide 2</div>
+        <div class="embla__slide">Slide 3</div>
+      </div>
+    </div>
+  `,
+  imports: [EmblaCarouselDirective],
+  standalone: true
+})
+export class CarouselComponent implements AfterViewInit {
+  @ViewChild(EmblaCarouselDirective) emblaRef: EmblaCarouselDirective
 
-## Further help
+  private emblaApi?: EmblaCarouselType
+  private options = { loop: false }
 
-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.
+  ngAfterViewInit() {
+    this.emblaApi = this.emblaRef.emblaApi
+  }
+}
+```
+
+
+<h2 align="center">Styling the carousel</h2>
+
+The element with the classname `embla` is needed to cover the scroll overflow. Its child element with the `container` classname is the scroll body that scrolls the slides. Continue by adding the following **CSS** to these elements:
+
+```css
+.embla {
+  overflow: hidden;
+}
+.embla__container {
+  display: flex;
+}
+.embla__slide {
+  flex: 0 0 100%;
+  min-width: 0;
+}
+```
+
+<h2 align="center">Accessing the carousel API</h2>
+
+The `emblaCarousel` directive takes the Embla Carousel [options](https://www.embla-carousel.com/api/options/) as part of its inputs. Additionally, you can access the [API](https://www.embla-carousel.com/api/) by using the `@ViewChild` decorator to access the carousel in `AfterViewInit` hook。
+
+> [!WARNING]
+>  Calling the following embla APIs directly will trigger too much ChangeDetection, which will lead to serious performance issues.
+
+<br />
+
+- `emblaApi.on()`
+- `emblaApi.scrollNext()`
+- `emblaApi.scrollPrev()`
+- `emblaApi.scrollTo()`
+
+Consider using the following methods which are wrapped with `ngZone.runOutsideAngular()`:
+
+- `EmblaCarouselDirective.scrollPrev()`
+- `EmblaCarouselDirective.scrollNext()`
+- `EmblaCarouselDirective.scrollTo()`
+
+```ts
+import { AfterViewInit, Component, ViewChild } from '@angular/core'
+import {
+  EmblaCarouselDirective,
+  EmblaCarouselType
+} from 'embla-carousel-angular'
+
+@Component({
+  selector: 'app-carousel',
+  template: `
+    <div class="embla" emblaCarousel [options]="options">
+      <div class="embla__container">
+        <div class="embla__slide">Slide 1</div>
+        <div class="embla__slide">Slide 2</div>
+        <div class="embla__slide">Slide 3</div>
+      </div>
+    </div>
+  `,
+  imports: [EmblaCarouselDirective],
+  standalone: true
+})
+export class CarouselComponent implements AfterViewInit {
+  @ViewChild(EmblaCarouselDirective) emblaRef: EmblaCarouselDirective
+
+  private emblaApi?: EmblaCarouselType
+  private options = { loop: false }
+
+  ngAfterViewInit() {
+    this.emblaApi = this.emblaRef.emblaApi
+  }
+}
+```
+
+<h2 align="center">Listening the carousel events</h2>
+
+The `emblaCarousel` directive also provides a custom event: `emblaChange` that forwards embla events, also wrapped in `ngZone.runOutsideAngular`. You need to listen by passing the specified event names into `subscribeToEvents` input on demand.
+
+```ts
+import { AfterViewInit, Component, ViewChild } from '@angular/core'
+import {
+  EmblaCarouselDirective,
+  EmblaCarouselType,
+  EmblaEventType
+} from 'embla-carousel-angular'
+
+@Component({
+  selector: 'app-carousel',
+  template: `
+    <div
+      class="embla"
+      emblaCarousel
+      [options]="options"
+      [subscribeToEvents]="subscribeToEvents"
+      (emblaChange)="onEmblaChange($event)"
+    >
+      <div class="embla__container">
+        <div class="embla__slide">Slide 1</div>
+        <div class="embla__slide">Slide 2</div>
+        <div class="embla__slide">Slide 3</div>
+      </div>
+    </div>
+  `,
+  imports: [EmblaCarouselDirective],
+  standalone: true
+})
+export class CarouselComponent implements AfterViewInit {
+  @ViewChild(EmblaCarouselDirective) emblaRef: EmblaCarouselDirective
+
+  private emblaApi?: EmblaCarouselType
+  private options = { loop: false }
+
+  public readonly subscribeToEvents: EmblaEventType[] = [
+    'init',
+    'pointerDown',
+    'pointerUp',
+    'slidesChanged',
+    'slidesInView',
+    'select',
+    'settle',
+    'destroy',
+    'reInit',
+    'resize',
+    'scroll'
+  ]
+
+  onEmblaChanged(event: EmblaEventType): void {
+    console.log(`Embla event triggered: ${event}`)
+  }
+
+  ngAfterViewInit() {
+    this.emblaApi = this.emblaRef.emblaApi
+  }
+}
+```
+
+<h2 align="center">Adding plugins</h2>
+
+Start by installing the plugin you want to use. In this example, we're going to install the [Autoplay](https://www.embla-carousel.com/plugins/autoplay/) plugin:
+
+```shell
+npm install embla-carousel-autoplay --save
+```
+
+The `emblaCarousel` directive inputs also accepts [plugins](https://www.embla-carousel.com/plugins/). Note that plugins need to be passed in an array like so:
+
+```ts
+import { AfterViewInit, Component, ViewChild } from '@angular/core'
+import {
+  EmblaCarouselDirective,
+  EmblaCarouselType
+} from 'embla-carousel-angular'
+import Autoplay from 'embla-carousel-autoplay'
+
+@Component({
+  selector: 'app-carousel',
+  template: `
+    <div class="embla" emblaCarousel [options]="options" [plugins]="plugins">
+      <div class="embla__container">
+        <div class="embla__slide">Slide 1</div>
+        <div class="embla__slide">Slide 2</div>
+        <div class="embla__slide">Slide 3</div>
+      </div>
+    </div>
+  `,
+  imports: [EmblaCarouselDirective],
+  standalone: true
+})
+export class CarouselComponent implements AfterViewInit {
+  @ViewChild(EmblaCarouselDirective) emblaRef: EmblaCarouselDirective
+
+  private emblaApi?: EmblaCarouselType
+  public options = { loop: false }
+  public plugins = [Autoplay()]
+
+  ngAfterViewInit() {
+    this.emblaApi = this.emblaRef.emblaApi
+  }
+}
+```
+
+<div align="center">
+  <strong>
+    <h2 align="center">Thanks</h2>
+  </strong>
+  <p align="center">
+     Thanks to <a href="https://github.com/davidjerleke">davidjerleke</a>, <a href="https://github.com/zip-fa">zip-fa</a> and <a href="https://github.com/JeanMeche">JeanMeche</a> for for the review and advice.
+  </p>
+</div>

angular.json

@@ -77,23 +77,29 @@
           "options": {
             "browserTarget": "embla-carousel-angular-monorepo:build"
           }
-        },
-        "test": {
-          "builder": "@angular-devkit/build-angular:karma",
+        }
+      }
+    },
+    "embla-carousel-angular": {
+      "projectType": "library",
+      "root": "projects/embla-carousel-angular",
+      "sourceRoot": "projects/embla-carousel-angular/src",
+      "prefix": "lib",
+      "architect": {
+        "build": {
+          "builder": "@angular-devkit/build-angular:ng-packagr",
           "options": {
-            "main": "src/test.ts",
-            "polyfills": "src/polyfills.ts",
-            "tsConfig": "tsconfig.spec.json",
-            "karmaConfig": "karma.conf.js",
-            "assets": [
-              "src/favicon.ico",
-              "src/assets"
-            ],
-            "styles": [
-              "src/styles.css"
-            ],
-            "scripts": []
-          }
+            "project": "projects/embla-carousel-angular/ng-package.json"
+          },
+          "configurations": {
+            "production": {
+              "tsConfig": "projects/embla-carousel-angular/tsconfig.lib.prod.json"
+            },
+            "development": {
+              "tsConfig": "projects/embla-carousel-angular/tsconfig.lib.json"
+            }
+          },
+          "defaultConfiguration": "production"
         }
       }
     }