Apply prettier formatting
This commit is contained in:
Michael Weimann
parent
1cac306093
commit
526645c791
1576 changed files with 65385 additions and 62478 deletions
115
README.md
115
README.md
|
|
@ -9,18 +9,18 @@
|
|||
[](https://sonarcloud.io/summary/new_code?id=matrix-react-sdk)
|
||||
[](https://sonarcloud.io/summary/new_code?id=matrix-react-sdk)
|
||||
|
||||
matrix-react-sdk
|
||||
================
|
||||
# matrix-react-sdk
|
||||
|
||||
This is a react-based SDK for inserting a Matrix chat/voip client into a web page.
|
||||
|
||||
This package provides the React components needed to build a Matrix web client
|
||||
using React. It is not useable in isolation, and instead must be used from
|
||||
using React. It is not useable in isolation, and instead must be used from
|
||||
a 'skin'. A skin provides:
|
||||
* Customised implementations of presentation components.
|
||||
* Custom CSS
|
||||
* The containing application
|
||||
* Zero or more 'modules' containing non-UI functionality
|
||||
|
||||
- Customised implementations of presentation components.
|
||||
- Custom CSS
|
||||
- The containing application
|
||||
- Zero or more 'modules' containing non-UI functionality
|
||||
|
||||
As of Aug 2018, the only skin that exists is
|
||||
[`vector-im/element-web`](https://github.com/vector-im/element-web/); it and
|
||||
|
|
@ -28,19 +28,19 @@ As of Aug 2018, the only skin that exists is
|
|||
be considered as a single project (for instance, matrix-react-sdk bugs
|
||||
are currently filed against vector-im/element-web rather than this project).
|
||||
|
||||
Translation Status
|
||||
------------------
|
||||
## Translation Status
|
||||
|
||||
[](https://translate.element.io/engage/element-web/?utm_source=widget)
|
||||
|
||||
Developer Guide
|
||||
---------------
|
||||
## Developer Guide
|
||||
|
||||
Platform Targets:
|
||||
* Chrome, Firefox and Safari.
|
||||
* WebRTC features (VoIP and Video calling) are only available in Chrome & Firefox.
|
||||
* Mobile Web is not currently a target platform - instead please use the native
|
||||
iOS (https://github.com/matrix-org/matrix-ios-kit) and Android
|
||||
(https://github.com/matrix-org/matrix-android-sdk2) SDKs.
|
||||
|
||||
- Chrome, Firefox and Safari.
|
||||
- WebRTC features (VoIP and Video calling) are only available in Chrome & Firefox.
|
||||
- Mobile Web is not currently a target platform - instead please use the native
|
||||
iOS (https://github.com/matrix-org/matrix-ios-kit) and Android
|
||||
(https://github.com/matrix-org/matrix-android-sdk2) SDKs.
|
||||
|
||||
All code lands on the `develop` branch - `master` is only used for stable releases.
|
||||
**Please file PRs against `develop`!!**
|
||||
|
|
@ -52,22 +52,23 @@ Our code style is also the same as Element's:
|
|||
https://github.com/vector-im/element-web/blob/develop/code_style.md
|
||||
|
||||
Code should be committed as follows:
|
||||
* All new components:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/src/components
|
||||
* Element-specific components:
|
||||
https://github.com/vector-im/element-web/tree/master/src/components
|
||||
* In practice, `matrix-react-sdk` is still evolving so fast that the
|
||||
maintenance burden of customising and overriding these components for
|
||||
Element can seriously impede development. So right now, there should be
|
||||
very few (if any) customisations for Element.
|
||||
* CSS: https://github.com/matrix-org/matrix-react-sdk/tree/master/res/css
|
||||
* Theme specific CSS & resources:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
|
||||
|
||||
- All new components:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/src/components
|
||||
- Element-specific components:
|
||||
https://github.com/vector-im/element-web/tree/master/src/components
|
||||
- In practice, `matrix-react-sdk` is still evolving so fast that the
|
||||
maintenance burden of customising and overriding these components for
|
||||
Element can seriously impede development. So right now, there should be
|
||||
very few (if any) customisations for Element.
|
||||
- CSS: https://github.com/matrix-org/matrix-react-sdk/tree/master/res/css
|
||||
- Theme specific CSS & resources:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
|
||||
|
||||
React components in matrix-react-sdk come in two different flavours:
|
||||
'structures' and 'views'. Structures are stateful components which handle the
|
||||
'structures' and 'views'. Structures are stateful components which handle the
|
||||
more complicated business logic of the app, delegating their actual presentation
|
||||
rendering to stateless 'view' components. For instance, the RoomView component
|
||||
rendering to stateless 'view' components. For instance, the RoomView component
|
||||
that orchestrates the act of visualising the contents of a given Matrix chat
|
||||
room tracks lots of state for its child components which it passes into them for
|
||||
visual rendering via props.
|
||||
|
|
@ -75,74 +76,72 @@ visual rendering via props.
|
|||
Good separation between the components is maintained by adopting various best
|
||||
practices that anyone working with the SDK needs to be aware of and uphold:
|
||||
|
||||
* Components are named with upper camel case (e.g. views/rooms/EventTile.js)
|
||||
- Components are named with upper camel case (e.g. views/rooms/EventTile.js)
|
||||
|
||||
* They are organised in a typically two-level hierarchy - first whether the
|
||||
- They are organised in a typically two-level hierarchy - first whether the
|
||||
component is a view or a structure, and then a broad functional grouping
|
||||
(e.g. 'rooms' here)
|
||||
|
||||
* The view's CSS file MUST have the same name (e.g. view/rooms/MessageTile.css).
|
||||
- The view's CSS file MUST have the same name (e.g. view/rooms/MessageTile.css).
|
||||
CSS for matrix-react-sdk currently resides in
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/res/css.
|
||||
|
||||
* Per-view CSS is optional - it could choose to inherit all its styling from
|
||||
- Per-view CSS is optional - it could choose to inherit all its styling from
|
||||
the context of the rest of the app, although this is unusual for any but
|
||||
* Theme specific CSS & resources:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
|
||||
structural components (lacking presentation logic) and the simplest view
|
||||
components.
|
||||
- Theme specific CSS & resources:
|
||||
https://github.com/matrix-org/matrix-react-sdk/tree/master/res/themes
|
||||
structural components (lacking presentation logic) and the simplest view
|
||||
components.
|
||||
|
||||
* The view MUST *only* refer to the CSS rules defined in its own CSS file.
|
||||
- The view MUST _only_ refer to the CSS rules defined in its own CSS file.
|
||||
'Stealing' styling information from other components (including parents)
|
||||
is not cool, as it breaks the independence of the components.
|
||||
|
||||
* CSS classes are named with an app-specific name-spacing prefix to try to
|
||||
avoid CSS collisions. The base skin shipped by Matrix.org with the
|
||||
matrix-react-sdk uses the naming prefix "mx_". A company called Yoyodyne
|
||||
Inc might use a prefix like "yy_" for its app-specific classes.
|
||||
- CSS classes are named with an app-specific name-spacing prefix to try to
|
||||
avoid CSS collisions. The base skin shipped by Matrix.org with the
|
||||
matrix-react-sdk uses the naming prefix "mx*". A company called Yoyodyne
|
||||
Inc might use a prefix like "yy*" for its app-specific classes.
|
||||
|
||||
* CSS classes use upper camel case when they describe React components - e.g.
|
||||
- CSS classes use upper camel case when they describe React components - e.g.
|
||||
.mx_MessageTile is the selector for the CSS applied to a MessageTile view.
|
||||
|
||||
* CSS classes for DOM elements within a view which aren't components are named
|
||||
- CSS classes for DOM elements within a view which aren't components are named
|
||||
by appending a lower camel case identifier to the view's class name - e.g.
|
||||
.mx_MessageTile_randomDiv is how you'd name the class of an arbitrary div
|
||||
within the MessageTile view.
|
||||
|
||||
* We deliberately use vanilla CSS 3.0 to avoid adding any more magic
|
||||
dependencies into the mix than we already have. App developers are welcome
|
||||
to use whatever floats their boat however. In future we'll start using
|
||||
- We deliberately use vanilla CSS 3.0 to avoid adding any more magic
|
||||
dependencies into the mix than we already have. App developers are welcome
|
||||
to use whatever floats their boat however. In future we'll start using
|
||||
css-next to pull in features like CSS variable support.
|
||||
|
||||
* The CSS for a component can override the rules for child components.
|
||||
For instance, .mx_RoomList .mx_RoomTile {} would be the selector to override
|
||||
- The CSS for a component can override the rules for child components.
|
||||
For instance, .mx*RoomList .mx_RoomTile {} would be the selector to override
|
||||
styles of RoomTiles when viewed in the context of a RoomList view.
|
||||
Overrides *must* be scoped to the View's CSS class - i.e. don't just define
|
||||
Overrides \_must* be scoped to the View's CSS class - i.e. don't just define
|
||||
.mx_RoomTile {} in RoomList.css - only RoomTile.css is allowed to define its
|
||||
own CSS. Instead, say .mx_RoomList .mx_RoomTile {} to scope the override
|
||||
only to the context of RoomList views. N.B. overrides should be relatively
|
||||
own CSS. Instead, say .mx_RoomList .mx_RoomTile {} to scope the override
|
||||
only to the context of RoomList views. N.B. overrides should be relatively
|
||||
rare as in general CSS inheritance should be enough.
|
||||
|
||||
* Components should render only within the bounding box of their outermost DOM
|
||||
- Components should render only within the bounding box of their outermost DOM
|
||||
element. Page-absolute positioning and negative CSS margins and similar are
|
||||
generally not cool and stop the component from being reused easily in
|
||||
different places.
|
||||
|
||||
Originally `matrix-react-sdk` followed the Atomic design pattern as per
|
||||
http://patternlab.io to try to encourage a modular architecture. However, we
|
||||
http://patternlab.io to try to encourage a modular architecture. However, we
|
||||
found that the grouping of components into atoms/molecules/organisms
|
||||
made them harder to find relative to a functional split, and didn't emphasise
|
||||
the distinction between 'structural' and 'view' components, so we backed away
|
||||
from it.
|
||||
|
||||
Github Issues
|
||||
-------------
|
||||
## Github Issues
|
||||
|
||||
All issues should be filed under https://github.com/vector-im/element-web/issues
|
||||
for now.
|
||||
|
||||
Development
|
||||
-----------
|
||||
## Development
|
||||
|
||||
Ensure you have the latest LTS version of Node.js installed.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue