Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/prose-im/prose-core-views
Prose core views. Shared messaging views across all platforms.
https://github.com/prose-im/prose-core-views
javascript vue
Last synced: about 1 month ago
JSON representation
Prose core views. Shared messaging views across all platforms.
- Host: GitHub
- URL: https://github.com/prose-im/prose-core-views
- Owner: prose-im
- License: mpl-2.0
- Created: 2021-12-13T18:08:42.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2024-04-04T17:31:09.000Z (9 months ago)
- Last Synced: 2024-04-04T18:42:54.962Z (9 months ago)
- Topics: javascript, vue
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@prose-im/prose-core-views
- Size: 538 KB
- Stars: 3
- Watchers: 4
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# prose-core-views
[](https://github.com/prose-im/prose-core-views/actions/workflows/test.yml) [](https://github.com/prose-im/prose-core-views/actions/workflows/build.yml) [](https://github.com/prose-im/prose-core-views/releases) [](https://www.npmjs.com/package/@prose-im/prose-core-views)
**Prose core views. Shared messaging views across all platforms.**
As Prose is a native cross-platform application, some views that are deemed too complex to build natively are shared between all apps. Those views are rendered in a lightweight and minimal Web view, and shared between mobile and desktop platforms. This also ensures that the Prose user experience stays consistent between all platforms.
Prose views are built on [`petite-vue`](https://github.com/vuejs/petite-vue), which is a super-lightweight minimal version of VueJS. This ensures that the rendering of elements such as lists stays efficient, usually even more efficient than using barebone native views. All assets get bundled using [`parcel`](https://parceljs.org/), which helps at easing development and produces an optimized production build.
Copyright 2022, Prose Foundation - Released under the [Mozilla Public License 2.0](./LICENSE.md).
_Tested at NodeJS version: `v20.7.0`_
## Preview
### Messaging view
_👉 The designs for all of the views are contained in the macOS app reference design [which can be found there](https://github.com/prose-im/prose-medley/blob/master/designs/app/prose-app-macos.sketch)._
## Installation
To install all the build dependencies, you first need to install NodeJS (version `12` and above).
Then, hit:
```
npm install
```
A pre-built package is also available:
```
npm add @prose-im/prose-core-views
```
## Build
Building the Prose core views is done per-target environment. Please check below for build instructions based on your target environment.
### Production target
To build Prose for a production environment (that is, usage within an actual Prose app), hit:
```
npm run build
```
### Development target
To build Prose for a development environment (that is, usage from a browser, while making changes), hit:
```
npm run dev
```
Then, open a Web browser and go to: [localhost:5000](http://localhost:5000/). Any saved changes will be hot-reloaded, meaning you will get live previews.
## Usage
Once built, all assets in `dist/` should be packaged within the Prose native app, and included in a Web view where relevant.
Serialized data should be passed to the view whenever its model needs to be updated.
### Messaging view
The messaging view can be included from path: `./dist/messaging.html`
#### 1. Pushing messages to the store
The messaging view exposes a programmatic API that lets applications manipulate its internal store:
- Check if a message exists: `MessagingStore.exists(messageId)`
- Resolve a message from the store: `MessagingStore.resolve(messageId)`
- Restore one or multiple past messages in the store (ie. prepend): `MessagingStore.restore(...messages)`
- Insert one or multiple messages in the store (ie. append): `MessagingStore.insert(...messages)`
- Update a message in the store: `MessagingStore.update(messageId, messageDiff)`
- Pull out a message from the store: `MessagingStore.retract(messageId)`
- Flush all content from the store: `MessagingStore.flush()`
- Highlight a message in the store: `MessagingStore.highlight(messageId)`
- Interact with a message action: `MessagingStore.interact(messageId, action, isActive)`
- Scroll to a message: `MessagingStore.scroll(messageId, isForced)`
- Toggle `backwards` or `forwards` loader in the store: `MessagingStore.loader(type, isVisible)`
- Identify an user identifier with its `name` and `avatar`: `MessagingStore.identify(userId, identity)`
All inserted message objects are required to hold the following keys: `id`, `type`, `date`, `content` and `from`. When updating an existing message, only modified keys need to be passed.
**Text messages are formatted as such:**
```json
{
"id": "b4d303b1-17c9-4863-81b7-bc5281f3590f",
"type": "text",
"date": "2021-12-20T19:15:03.000Z",
"from": "[email protected]",
"content": "Hello! This is a text message.",
"metas": {
"encrypted": true,
"edited": false,
"transient": false,
"lastRead": true
},
"reactions": [
{
"reaction": "🤠",
"authors": ["[email protected]", "[email protected]"]
},
{
"reaction": "👋",
"authors": ["[email protected]"]
}
]
}
```
**File attachments (on any message type) are formatted as such:**
```json
{
"id": "07b4af91-c5f4-45be-98f4-77f554c042c8",
"type": "text",
"date": "2021-12-21T09:04:01.000Z",
"from": "[email protected]",
"content": "Check this image out!",
"files": [
{
"name": "crisp-keep-calm.jpg",
"type": "image/jpeg",
"url": "https://crisp.chat/static/blog/content/images/size/w600/2021/03/12---3-Simple-Actions-to-Tackle-Email-Overload.jpg",
"size": {
"width": 1920,
"height": 1080
}
}
],
"metas": {
"encrypted": false,
"edited": false,
"transient": false,
"lastRead": true
},
"reactions": []
}
```
#### 2. Adjusting message view context options
The message view exposes context helpers, that let some options be adjusted at runtime.
As soon as the view is available, the following methods can be called:
**Option getters:**
- Get interface language: `MessagingContext.getLanguage()`
- Get style platform: `MessagingContext.getStylePlatform()`
- Get style renderer: `MessagingContext.getStyleRenderer()`
- Get style theme: `MessagingContext.getStyleTheme()`
- Get style modifier: `MessagingContext.getStyleModifier()`
- Get account user identifier: `MessagingContext.getAccountUserId()`
**Option setters:**
- Set interface language: `MessagingContext.setLanguage(code)` (where `code` is supported locale code)
- Set style platform: `MessagingContext.setStylePlatform(platform)` (where `platform` is any of: `web`, `macos`)
- Set style renderer: `MessagingContext.setStyleRenderer(renderer)` (where `renderer` can be eg.: `firefox`, `chrome`, `safari`)
- Set style theme: `MessagingContext.setStyleTheme(theme)` (where `theme` is any of: `light`, `dark`)
- Set style modifier: `MessagingContext.setStyleModifier(name, value)` (where `name` is any of: `scroll`)
- Set account user identifier: `MessagingContext.setAccountUserId(userId)` (where `userId` is a valid Jabber IDentifier)
#### 3. Subscribing to messaging events
The message view may raise events when certain things happen, such as when the user interacts with a message.
Events can be subscribed to, on per-namespace basis:
- Subscribe to an event namespace: `MessagingEvent.on(namespace, handler)`
- Unsubscribe from an event namespace: `MessagingEvent.off(namespace)`
The following namespaces are available for use:
- `message:author:identity`: show user identity for a message author (eg. user overs the message avatar or name)
- `message:actions:view`: show the list of actions for a message (eg. user right-clicks on a message)
- `message:reactions:view`: show the list of reactions that can be sent for message
- `message:reactions:authors`: show the list of reaction authors for reaction on message (eg. user overs the reaction)
- `message:reactions:react`: react to a message (eg. user clicks on an existing reaction to send it or retract it)
- `message:file:view`: view a file from a message (eg. user clicks on a file to expand or download the file)
- `message:link:open`: open a link contained in a message (eg. user clicks on a link)
- `message:history:view`: notify when a message from history enters or leaves view area, with the `visible` and `hidden` states (eg. scrolling up or down in the timeline)
- `message:history:seek`: request to load `backwards` or `forwards` history (eg. scrolling back in time to load past messages)
## License
Licensing information can be found in the [LICENSE.md](./LICENSE.md) document.
## :fire: Report A Vulnerability
If you find a vulnerability in any Prose system, you are more than welcome to report it directly to Prose Security by sending an encrypted email to [[email protected]](mailto:[email protected]). Do not report vulnerabilities in public GitHub issues, as they may be exploited by malicious people to target production systems running an unpatched version.
**:warning: You must encrypt your email using Prose Security GPG public key: [:key:57A5B260.pub.asc](https://files.prose.org/public/keys/gpg/57A5B260.pub.asc).**