# Cotalk

A comment plugin based on Codeberg issues.

Cotalk is a modern comment component based on Codeberg Issue and Preact.

## Features

- Authentication with Codeberg account
- Serverless, all comments will be stored as Codeberg issues
- Both personal and organization Codeberg projects can be used to store comments
- Localization, support multiple languages [en, zh-CN, zh-TW, es-ES, fr, ru, de, pl, ko, fa, ja]
- Facebook-like distraction free mode (Can be enabled via the `distractionFreeMode` option)
- Hotkey submit comment (cmd|ctrl + enter)

## Install

Two ways.

- npm install

```sh
npm i --save cotalk
```

```js
import 'cotalk/dist/cotalk.css'
import Cotalk from 'cotalk'
```

## Usage
Firstly, you need choose a public Codeberg repository (existed or create a new one) for store comments,

Then create A **Codeberg Application** if you don't have one, [Click here to register](https://codeberg.org/user/settings/applications) a new one. 
**Note:** You must specify the website domain url in the `Authorization callback URL` field.

Lastly, you can choose how to apply to the page as below:

### Method One
Add a container to your page:

```html
<div id="cotalk-container"></div>
```

Then use the Javascript code below to generate the Cotalk plugin:

```js
const cotalk = new Cotalk({
  clientID: 'Codeberg Application Client ID',
  clientSecret: 'Codeberg Application Client Secret',
  repo: 'Codeberg repo',      // The repository of store comments,
  owner: 'Codeberg repo owner',
  admin: ['Codeberg repo owner and collaborators, only these guys can initialize codeberg issues'],
  id: location.pathname,      // Ensure uniqueness and length less than 50
  distractionFreeMode: false  // Facebook-like distraction free mode
})

cotalk.render('cotalk-container')
```

### Method Two: Use in React

Import the Cotalk with

```jsx
import CotalkComponent from "cotalk/dist/cotalk-component";
```

And use the component like

```jsx
<CotalkComponent options={{
  clientID: "...",
  // ...
  // options below
}} />
```

## Options

- **clientID** `String`

  **Required**. Codeberg Application Client ID.

- **clientSecret** `String`

  **Required**. Codeberg Application Client Secret.

- **repo** `String`

  **Required**. Codeberg repository.

- **owner** `String`

  **Required**. Codeberg repository owner. Can be personal user or organization.

- **admin** `Array`

  **Required**. Codeberg repository owner and collaborators. (Users who having write access to this repository)

- **id** `String`

  Default: `location.href`.

  The unique id of the page. Length must less than 50.

  Note: You can use regex to extract certain path of the URL as the id. E.g., `location.href.match('/(?<=posts/)(.*)(?=/)/')[1]`

- **number** `Number`

  Default: `-1`.

  The issue ID of the page, if the `number` attribute is not defined, issue will be located using `id`.

- **labels** `Array`

  Default: `['Gitalk']`.

  GitHub issue labels.

- **title** `String`

  Default: `document.title`.

  GitHub issue title.

- **body** `String`

  Default: `location.href + header.meta[description]`.

  GitHub issue body.

- **language** `String`

  Default: `navigator.language || navigator.userLanguage`.

  Localization language key, support [`en`, `zh-CN`, `zh-TW`, `es-ES`, `fr`, `ru`, `de`, `pl`, `ko`, `fa`, `ja`].

- **perPage** `Number`

  Default: `10`.

  Pagination size, with maximum 100.

- **distractionFreeMode** `Boolean`

  Default: false.

  Facebook-like distraction free mode.

- **pagerDirection** `String`

  Default: 'last'

  Comment sorting direction, available values are `last` and `first`.

- **createIssueManually** `Boolean`

  Default: `false`.

  By default, Gitalk will create a corresponding github issue for your every single page automatically when the logined user is belong to the `admin` users. You can create it manually by setting this option to `true`.

- **flipMoveOptions** `Object`

  Default:
  ```js
    {
      staggerDelayBy: 150,
      appearAnimation: 'accordionVertical',
      enterAnimation: 'accordionVertical',
      leaveAnimation: 'accordionVertical',
    }
  ```

  Comment list animation. [Reference](https://github.com/joshwcomeau/react-flip-move/blob/master/documentation/enter_leave_animations.md)

- **enableHotKey** `Boolean`

  Default: `true`.

  Enable hot key (cmd|ctrl + enter) submit comment.


## Instance Methods

- **render(String/HTMLElement)**

  Init render and mount plugin.

## TypeScript

TypeScript definitions for options and Gitalk class come with the package and should be automatically detected.

Definitions for React component usage are not included.

## Contributing

1. [Fork the repository](https://github.com/gitalk/gitalk/fork) and create your branch from master
2. If you've added code that should be tested, add tests!
3. If you've changed APIs, update the documentation.
4. Ensure the test suite passes (npm test).
5. Make sure your code lints (npm run lint).
6. Commit your changes (git commit) [Commit Message Format Reference](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines)

## Similar Projects

- [gitment](https://github.com/imsun/gitment)
- [vssue](https://vssue.js.org)

## LICENSE

MIT

[npm-version-image]: https://img.shields.io/npm/v/gitalk.svg?style=flat-square
[npm-version-url]: https://www.npmjs.com/package/gitalk
[cdnjs-version-image]: https://img.shields.io/cdnjs/v/gitalk.svg?style=flat-square
[cdnjs-version-url]: https://cdnjs.com/libraries/gitalk
[david-dm-image]: https://david-dm.org/gitalk/gitalk.svg?style=flat-square
[david-dm-url]: https://david-dm.org/gitalk/gitalk
[travis-image]: https://img.shields.io/travis/gitalk/gitalk/master.svg?style=flat-square
[travis-url]: https://travis-ci.org/gitalk/gitalk
[coveralls-image]: https://img.shields.io/coveralls/gitalk/gitalk/master.svg?style=flat-square
[coveralls-url]: https://coveralls.io/github/gitalk/gitalk
[gzip-size]: https://img.badgesize.io/https://unpkg.com/gitalk/dist/gitalk.min.js?compression=gzip&style=flat-square
[gzip-url]: https://unpkg.com/gitalk/dist/gitalk.min.js