npm package: @gnehcwu/kquery
Description: A simplified jQuery-like capable library
Author: Cheng Wu
Latest version: 0.0.1

 <div align="center">
  <h1>kQuery</h1>
  <p>A simplified jQuery-like capable library</p>
</div>

## 📦 Install from npm
```shell
npm install @gnehcwu/kQuery
```

## 🌈 Basic Usage

```js
import kQuery from 'kquery';

kQuery('.item')
  .replaceWith(kQuery('.itemReplacement'))
  .style({
    color: '#000',
  });
```

This gets all the [DOM elements](https://developer.mozilla.org/en-US/docs/Web/API/Element) matching the [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) `.item`, replaces them with all the elements matching `.itemReplacement`, and then changes the CSS `color` property of the DOM element.

## 🛠 API
The API to implement is very similar to the [jQuery API](https://api.jquery.com).

### `kQuery(cssSelectorString)`

Select matching elements on the page.

- Reads a CSS selector string
- Returns a kQuery collection (`kCollection` or `collection` in this assignment)

#### Example

<h6 align="center">index.html</h6>

```html
<div class="item">Hello</div>
<div class="item">World!</div>
```

<h6 align="center">index.js</h6>

```js
const kCollection = kQuery('.item');
```

#### Result

`kCollection` now contains the elements matching the CSS selector `.item`.

### `kCollection.replaceWith(kCollection)`

- Replaces the current collection with another one
- Returns the new collection

#### Example

<h6 align="center">index.html</h6>

```html
<div class="items">
  <div class="item">Some</div>
  <div class="item">Item</div>
</div>

<span class="itemReplacement">Hello</span>
<span class="itemReplacement">World!</span>
```

<h6 align="center">index.js</h6>

```js
kQuery('.item').replaceWith(kQuery('.itemReplacement'));
```

#### DOM result

```html
<div class="items">
  <span class="itemReplacement">Hello</span>
  <span class="itemReplacement">World!</span>
  <span class="itemReplacement">Hello</span>
  <span class="itemReplacement">World!</span>
</div>
```

### `kCollection.style(Object)`

- Updates the style of the current collection
- Returns the current collection

#### Example

<h6 align="center">index.html</h6>

```html
<div class="item">Hello World!</div>
```

<h6 align="center">index.js</h6>

```js
kQuery('.item').style({ color: 'red' });
```

#### Result

`Hello World!` is now displayed in red color.

### `kCollection.remove()`

- Removes the current collection from the DOM
- Returns an empty collection to allow the chain of commands to continue

#### Example

<h6 align="center">index.html</h6>

```html
<div class="item">Some</div>
<div class="item">Item</div>
<div>Hello World!</div>
```

<h6 align="center">index.js</h6>

```js
kQuery('.item').remove();
```

#### DOM result

```html
<div>Hello World!</div>
```

### `kCollection.find(cssSelectorString)`

- Searches the current collection for matching elements and replaces the current collection
- Returns the new collection

#### Example

<h6 align="center">index.html</h6>

```html
<div class="item">Hello <span>World!</span></div>
<div class="item">World! <span>Hello</span></div>
```

<h6 align="center">index.js</h6>

```js
const kCollection = kQuery('.item').find('span');
```

#### Result

`kCollection` contains two spawn elements.

### `kCollection.get()`

- Returns an [`Array`](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/Array) of all DOM elements in the `kCollection`

_After this call, the `kQuery` chain ends since you get a regular `Array` and not a `kCollection`._

#### Example

<h6 align="center">index.html</h6>

```html
<div class="item">Hello</div>
<div class="item">World!</div>
```

<h6 align="center">index.js</h6>

```js
const domElements = kQuery('.item').get();
```

**Result:**

`domElements` contains an array of DOM elements with two elements.

## 🥳 Contribution Guides

Please have a read of guides for code of conduct and contributing.

## 💎 How to run & build locally

```shell
// After git clone the repo, cd to project folder
npm install
npm start
```
###  👉 For running test locally
```shell
npm run test
```