@salla.sa/twilight-components 1.0.152 → 1.0.154
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +195 -36
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,62 +1,221 @@
|
|
|
1
|
-
|
|
1
|
+
<div id="top"></div>
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
<br />
|
|
4
|
+
<div align="center">
|
|
5
|
+
<a href="https://salla.dev">
|
|
6
|
+
<img src="https://salla.dev/wp-content/themes/salla-portal/dist/img/salla-logo.svg" alt="Logo" width="80" height="80">
|
|
7
|
+
</a>
|
|
8
|
+
<h1 align="center">Twilight JS Web Components</h1>
|
|
9
|
+
<p align="center">
|
|
10
|
+
A ready-designed and styled set of js web components for Salla stores.
|
|
11
|
+
<br />
|
|
12
|
+
<a href="https://salla.dev/"><strong>Explore our blogs »</strong></a>
|
|
13
|
+
<br />
|
|
14
|
+
<br />
|
|
15
|
+
<a href="https://github.com/SallaApp/Salla-CLI/issues/new">Report Bug</a> ·
|
|
16
|
+
<a href="https://github.com/SallaApp/Salla-CLI/discussions/new">Request Feature</a> .
|
|
17
|
+
<a href="https://t.me/salladev"></Salla Developers></a> .
|
|
18
|
+
<a href="https://salla.stoplight.io/docs/twilight-themes-documentation/c1a2717de7e4b-overview">Offical Documentation</a>
|
|
19
|
+
</p>
|
|
20
|
+
</div>
|
|
4
21
|
|
|
5
|
-
|
|
22
|
+
<!-- TABLE OF CONTENTS -->
|
|
23
|
+
<details open>
|
|
24
|
+
<summary>Table of Contents</summary>
|
|
25
|
+
<ol>
|
|
26
|
+
<li>
|
|
27
|
+
<a href="#overview">Overview</a>
|
|
28
|
+
</li>
|
|
29
|
+
<li>
|
|
30
|
+
<a href="#getting-started">Getting Started</a>
|
|
31
|
+
<ul>
|
|
32
|
+
<li><a href="#benefits">List of Twilight JS Web Components</a></li>
|
|
33
|
+
<li><a href="#benefits">Benefits</a></li>
|
|
34
|
+
</ul>
|
|
35
|
+
<li><a href="#installation">Installation</a></li>
|
|
36
|
+
<li><a href="#usage">Usage</a></li>
|
|
37
|
+
<li><a href="#events">Events</a></li>
|
|
38
|
+
<li><a href="#support">Support</a></li>
|
|
39
|
+
<li><a href="#contributing">Contributing</a></li>
|
|
40
|
+
<li><a href="#credits">Credits</a></li>
|
|
41
|
+
<li><a href="#license">License</a></li>
|
|
42
|
+
</li>
|
|
43
|
+
</ol>
|
|
44
|
+
</details>
|
|
45
|
+
<!-- Overview -->
|
|
6
46
|
|
|
7
|
-
|
|
8
|
-
- [*] [salla-search-modal](src/components/search-modal/readme.md)
|
|
9
|
-
- [ ] [salla-login](src/components/search-modal/readme.md)
|
|
47
|
+
## Overview
|
|
10
48
|
|
|
11
|
-
|
|
49
|
+
**Twilight** comes with a ready-designed and styled set of web components for Salla stores. For example, ready components to display the login form, product availability section, search bar, localization menu, and many more. **Twilight JS Web Components** are a collection of high-level building blocks and reusable web components that can be built together to swiftly develop the UI for custom Salla Themes, governed by clear guidelines.
|
|
12
50
|
|
|
13
|
-
### npm
|
|
14
51
|
|
|
15
|
-
|
|
16
|
-
npm install @salla.sa/twilight-components
|
|
17
|
-
```
|
|
52
|
+
<br/>
|
|
18
53
|
|
|
19
|
-
|
|
54
|
+
## Getting Started
|
|
20
55
|
|
|
21
|
-
|
|
22
|
-
yarn add @salla.sa/twilight-components
|
|
23
|
-
```
|
|
56
|
+
**JS Web Components** were built from the ground up to be simple to learn and use, with various thoughtfully constructed user interface components. Its complete compatibility with the themes' structure and architecture makes it easy to customize, as the documentation explains.
|
|
24
57
|
|
|
25
|
-
|
|
58
|
+
### List of Twilight JS Web Components
|
|
59
|
+
|
|
60
|
+
Below is a list of the ready-made Twilight JS Web Components which can be used easily. Following, in this part of the document, each component is explained in detail.
|
|
61
|
+
|
|
62
|
+
Every web component comes with a list of **properties and events** that make that component customizable. Besides, each web component uses methods from the [**Twilight JS SDK**](https://salla.stoplight.io/docs/twilight-themes-documentation/3ac843cae76a2-overview) to fetch any needed data from the backend.
|
|
63
|
+
|
|
64
|
+
| Component | Code Tag | Description |
|
|
65
|
+
| --------------------------------------------------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
66
|
+
| [Branches](https://salla.stoplight.io/docs/twilight-themes-documentation/70422e4259f02-branches) | `salla-branches` | Header component that redirects merchants to a specific branch owned by the store. |
|
|
67
|
+
| [Button](https://salla.stoplight.io/docs/twilight-themes-documentation/f973f4bbc269b-button) | `salla-button` | Customizable Button component. |
|
|
68
|
+
| [Infinite Scroll](https://salla.stoplight.io/docs/twilight-themes-documentation/ede37d6e84859-infinite-scroll) | `salla-infinite-scroll` | Items that can be scrolled infinitely. |
|
|
69
|
+
| [Localization](https://salla.stoplight.io/docs/twilight-themes-documentation/559cc67721f74-localization) | `salla-localization-modal` | Modal dialoug which merchants can select languages/currencies from. |
|
|
70
|
+
| [Login](https://salla.stoplight.io/docs/twilight-themes-documentation/0796e7fb0464b-login) | `salla-login-modal` | Ready-made sign-in/sign-up modal. |
|
|
71
|
+
| [Modal](https://salla.stoplight.io/docs/twilight-themes-documentation/32babc5658e91-modal) | `salla-modal` | Modal dialoug that momentarily prevents interactions. |
|
|
72
|
+
| [Offer](https://salla.stoplight.io/docs/twilight-themes-documentation/1bb759464b884-offer) | `salla-offer-modal` | Modal dialoug which merchants can select offers related to product(s) they added to the cart. |
|
|
73
|
+
| [Product Availability](https://salla.stoplight.io/docs/twilight-themes-documentation/2d4dd6d9016bf-product-availability) | `salla-product-availability` | Modal dialoug where registered merchants can be notified when a product is available. |
|
|
74
|
+
| [Rating](https://salla.stoplight.io/docs/twilight-themes-documentation/1c81291fb13c7-rating) | `salla-rating-modal` | Modal dialoug prompting merchants to rate a store/product/shipping company after an order purchase has been completed. |
|
|
75
|
+
| [Search](https://salla.stoplight.io/docs/twilight-themes-documentation/8379c482cea4b-search) | `salla-search` | Conduct the search capbility within the store. |
|
|
76
|
+
| [Tel Input](https://salla.stoplight.io/docs/twilight-themes-documentation/82c778cf6f21f-tel-input) | `salla-tel-input` | Input field for accepting merchants' phone number, with country key/code prefix. |
|
|
77
|
+
| [Verify](https://salla.stoplight.io/docs/twilight-themes-documentation/634794ef9a954-verify) | `salla-verify` | Dependent Salla Login component where merchants who have updated their Profile details are followed up with a verification modal. |
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
<p align="right">(<a href="#top">back to top</a>)</p>
|
|
81
|
+
|
|
82
|
+
### Benefits
|
|
83
|
+
|
|
84
|
+
#### Clean, simple, and standardized.
|
|
85
|
+
Developers will follow standards and let users fall in love with the user experience with ready-made components and beautiful (yet changeable) themes. Developers can use a stylistic guideline and functional designs to create huge Themes with UI Component modules.
|
|
86
|
+
|
|
87
|
+
#### Using Twilight JS SDK
|
|
88
|
+
|
|
89
|
+
Twilight Web Components are using the [**Twilight JS SDK**](https://salla.stoplight.io/docs/twilight-themes-documentation/3ac843cae76a2-overview), which allows communication between the frontend and backend using specific REST API.
|
|
90
|
+
|
|
91
|
+
#### Ecosystem
|
|
92
|
+
|
|
93
|
+
Twilight Web Components are maintained by a full-time core team and a large community of developers and contributors. This is because Twilight helps developers collaborate.
|
|
26
94
|
|
|
95
|
+
<p align="right">(<a href="#top">back to top</a>)</p>
|
|
96
|
+
|
|
97
|
+
## Installation
|
|
98
|
+
|
|
99
|
+
Installing the JS Web Components can be done by running the following commands in the command line:
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
```npm title="NPM Installation Command"
|
|
103
|
+
npm install @salla.sa/twilight-components --save
|
|
27
104
|
```
|
|
28
|
-
# npm link
|
|
29
|
-
npm install @salla.sa/twilight-components
|
|
30
|
-
npm install @salla.sa/twilight-tailwind-theme
|
|
31
|
-
// or npm install {full-path-of-folder}
|
|
32
105
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
// include prod
|
|
36
|
-
require('@salla.sa/twilight-components')
|
|
106
|
+
```yarn title="Yarn Installation Command"
|
|
107
|
+
yarn add @salla.sa/twilight-components
|
|
37
108
|
```
|
|
38
109
|
|
|
110
|
+
Then base in the usage the import of the components to the `scss/js` files
|
|
39
111
|
|
|
40
|
-
|
|
112
|
+
```SCSS title="Import Command"
|
|
113
|
+
@import "~@salla.sa/twilight-components/dist/twilight-components/twilight-components";
|
|
114
|
+
```
|
|
41
115
|
|
|
42
|
-
|
|
116
|
+
```JS title="Import Command"
|
|
117
|
+
import {
|
|
118
|
+
applyPolyfills,
|
|
119
|
+
defineCustomElements as SallaWebComponents
|
|
120
|
+
} from '@salla.sa/twilight-components/loader';
|
|
43
121
|
|
|
122
|
+
applyPolyfills().then(() => {
|
|
123
|
+
SallaWebComponents(window);
|
|
124
|
+
});
|
|
44
125
|
```
|
|
45
|
-
|
|
46
|
-
|
|
126
|
+
|
|
127
|
+
Another common approach for loading Twilight Components is to use the version hosted on the CDN. The components can be loaded via `<script>` and `<link>` tags in the head of the HTML document
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
```html title="Code Snippet"
|
|
131
|
+
<script
|
|
132
|
+
type="module"
|
|
133
|
+
src="https://unpkg.com/@esri/calcite-components@1.0.0-beta.80/dist/calcite/calcite.esm.js"
|
|
134
|
+
></script>
|
|
135
|
+
|
|
136
|
+
<link
|
|
137
|
+
rel="stylesheet"
|
|
138
|
+
type="text/css"
|
|
139
|
+
href="https://unpkg.com/@esri/calcite-components@1.0.0-beta.80/dist/calcite/calcite.css"
|
|
140
|
+
/>
|
|
47
141
|
```
|
|
48
142
|
|
|
49
|
-
|
|
143
|
+
<p align="right">(<a href="#top">back to top</a>)</p>
|
|
144
|
+
|
|
145
|
+
## Usage
|
|
146
|
+
|
|
50
147
|
|
|
51
|
-
|
|
148
|
+
After installation, Components can be easily added in the basic HTML markup, as shown in the following example:
|
|
52
149
|
|
|
150
|
+
```html title="Salla Button Configs"
|
|
151
|
+
// Salla Button component
|
|
152
|
+
<salla-button fill="outline" color="dark">Hello World 👋</salla-button>
|
|
153
|
+
|
|
154
|
+
// Salla Telephone Input component
|
|
155
|
+
<salla-tel-input onclick="telInput.isValid()" country-code="sa"
|
|
156
|
+
country-key="+966" mobile="555555555">
|
|
157
|
+
|
|
158
|
+
// Salla Product Availability component
|
|
159
|
+
<salla-product-availability channels="sms,mobile,email" is-subscribed="false">
|
|
160
|
+
</salla-product-availability>
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
## Events
|
|
165
|
+
|
|
166
|
+
We recommend using DOM events, but we also provide custom events to help with specific event kinds. All custom events are always documented on their own documentation page for each component.
|
|
167
|
+
|
|
168
|
+
```js title="Modal Event Initialization"
|
|
169
|
+
// Save reference to the modal component below
|
|
170
|
+
var modal = document.querySelector("salla-modal");
|
|
171
|
+
|
|
172
|
+
// Listen for open events
|
|
173
|
+
modal.addEventListener("modalOpened", function () {
|
|
174
|
+
console.log("Modal Opened");
|
|
175
|
+
});
|
|
53
176
|
```
|
|
54
|
-
|
|
177
|
+
|
|
178
|
+
Moreover, developers can detect when a component has been loaded, as Twilight registers its components using the standard Web Components API's CustomElementsRegistry object. This object also provides a `whenDefined` function, which takes a component name and returns a promise. When the component is defined, the promise will be fulfilled:
|
|
179
|
+
|
|
180
|
+
```js title="Window Custom Element Configs"
|
|
181
|
+
window.customElements.whenDefined("salla-button").then(() => {
|
|
182
|
+
console.log("Salla Button is defined!");
|
|
183
|
+
});
|
|
55
184
|
```
|
|
56
185
|
|
|
57
|
-
|
|
186
|
+
<p align="right">(<a href="#top">back to top</a>)</p>
|
|
187
|
+
|
|
188
|
+
## Support
|
|
189
|
+
|
|
190
|
+
The team is always here to help you. Happen to face an issue? Want to report a bug? You can submit one here on Github using the [Issue Tracker](https://github.com/SallaApp/twilight-vscode-extension/issues/new). If you still have any questions, please contact us via the [Telegram Bot](https://t.me/SallaSupportBot) or join in the Global Developer Community on [Telegram](https://t.me/salladev).
|
|
191
|
+
|
|
192
|
+
<p align="right">(<a href="#top">back to top</a>)</p>
|
|
193
|
+
|
|
194
|
+
## Contributing
|
|
195
|
+
|
|
196
|
+
Contributions are what make the open-source community such an amazing place to learn, inspire, and create.
|
|
197
|
+
Any contributions you make are **greatly appreciated**.
|
|
198
|
+
|
|
199
|
+
If you have a suggestion that would make this better, please fork the repo and create a pull request.
|
|
200
|
+
You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
|
|
201
|
+
|
|
202
|
+
1. Fork the Project
|
|
203
|
+
2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
|
|
204
|
+
3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
|
|
205
|
+
4. Push to the Branch (`git push origin feature/AmazingFeature`)
|
|
206
|
+
5. Open a Pull Request
|
|
207
|
+
|
|
208
|
+
<p align="right">(<a href="#top">back to top</a>)</p>
|
|
209
|
+
|
|
210
|
+
## Credits
|
|
211
|
+
|
|
212
|
+
- [Salla](https://github.com/sallaApp)
|
|
213
|
+
- [All Contributors](../../contributors)
|
|
214
|
+
|
|
215
|
+
<p align="right">(<a href="#top">back to top</a>)</p>
|
|
216
|
+
|
|
217
|
+
## License
|
|
218
|
+
|
|
219
|
+
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
|
|
58
220
|
|
|
59
|
-
|
|
60
|
-
1. Everytime you change the utilities json you should run this command to update the output of tailwind css (TODO :: make it automatic with watch command)
|
|
61
|
-
2. Change the store settings in `src/global/app.ts`
|
|
62
|
-
3. Run watch `npm run watch`
|
|
221
|
+
<p align="right">(<a href="#top">back to top</a>)</p>
|