@scania/tegel 0.0.71-beta → 0.0.72
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
ADDED
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
[](https://www.npmjs.com/package/@scania/tegel)
|
|
2
|
+
[](https://tegel-storybook.netlify.app/)
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
# Tegel Design System
|
|
7
|
+
|
|
8
|
+
https://tegel.scania.com/
|
|
9
|
+
|
|
10
|
+
The design system supports the design and development of digital solutions at Scania. The purpose is to secure a coherent, premium brand and user experience across all of Scania's digital touchpoints.
|
|
11
|
+
|
|
12
|
+
- [Status](#status)
|
|
13
|
+
- [Installation](#installation)
|
|
14
|
+
- [React with typescript](#with-typescript)
|
|
15
|
+
- [React with javascript](#with-javascript)
|
|
16
|
+
- [Angular](#angular)
|
|
17
|
+
- [HTML/JS](#html)
|
|
18
|
+
- [Browser support](#browser-support)
|
|
19
|
+
- [Code conventions](#code-conventions)
|
|
20
|
+
- [Development environment](#setting-up-the-development-environment)
|
|
21
|
+
- [Community](#community)
|
|
22
|
+
|
|
23
|
+
## Status
|
|
24
|
+
|
|
25
|
+
This package is currently in a pre-beta stage. We are now working hard towards a 1.0-beta release, but if you want to try out the package today you can! It's available via NPM and can be installed using the installation guide below.
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
### React
|
|
30
|
+
|
|
31
|
+
#### with Typescript
|
|
32
|
+
|
|
33
|
+
1. Run `npm install @scania/tegel`
|
|
34
|
+
2. src folder create a file called `register-webcomponents.ts`
|
|
35
|
+
3. Paste the following into that file:
|
|
36
|
+
|
|
37
|
+
```ts
|
|
38
|
+
import { defineCustomElements, JSX as LocalJSX } from '@scania/tegel/loader';
|
|
39
|
+
import { DetailedHTMLProps, HTMLAttributes } from 'react';
|
|
40
|
+
|
|
41
|
+
type StencilProps<T> = {
|
|
42
|
+
[P in keyof T]?: Omit<T[P], 'ref'> | HTMLAttributes<T>;
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
type ReactProps<T> = {
|
|
46
|
+
[P in keyof T]?: DetailedHTMLProps<HTMLAttributes<T[P]>, T[P]>;
|
|
47
|
+
};
|
|
48
|
+
|
|
49
|
+
type StencilToReact<T = LocalJSX.IntrinsicElements, U = HTMLElementTagNameMap> = StencilProps<T> &
|
|
50
|
+
ReactProps<U>;
|
|
51
|
+
|
|
52
|
+
declare global {
|
|
53
|
+
export namespace JSX {
|
|
54
|
+
interface IntrinsicElements extends StencilToReact {}
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
defineCustomElements(window);
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
4. In your index.tsx import `register-webcomponents.ts`
|
|
62
|
+
|
|
63
|
+
```tsx
|
|
64
|
+
import React from 'react';
|
|
65
|
+
import ReactDOM from 'react-dom/client';
|
|
66
|
+
import './index.css';
|
|
67
|
+
import App from './App';
|
|
68
|
+
import reportWebVitals from './reportWebVitals';
|
|
69
|
+
import './register-webcomponents';
|
|
70
|
+
|
|
71
|
+
const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
|
|
72
|
+
root.render(
|
|
73
|
+
<React.StrictMode>
|
|
74
|
+
<App />
|
|
75
|
+
</React.StrictMode>,
|
|
76
|
+
);
|
|
77
|
+
|
|
78
|
+
reportWebVitals();
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
5. In your global css file (usually `App.css`) import the tegel stylesheet.
|
|
82
|
+
|
|
83
|
+
```css
|
|
84
|
+
@import url('@scania/tegel/dist/tegel/tegel.css');
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
#### with Javascript
|
|
88
|
+
|
|
89
|
+
1. Run `npm install @scania/tegel`
|
|
90
|
+
2. In your index.jsx define the custom components:
|
|
91
|
+
|
|
92
|
+
```jsx
|
|
93
|
+
import React from 'react';
|
|
94
|
+
import ReactDOM from 'react-dom/client';
|
|
95
|
+
import './index.css';
|
|
96
|
+
import App from './App';
|
|
97
|
+
import reportWebVitals from './reportWebVitals';
|
|
98
|
+
import { defineCustomElements } from '@scania/tegel/loader';
|
|
99
|
+
|
|
100
|
+
const root = ReactDOM.createRoot(document.getElementById('root'));
|
|
101
|
+
root.render(
|
|
102
|
+
<React.StrictMode>
|
|
103
|
+
<App />
|
|
104
|
+
</React.StrictMode>,
|
|
105
|
+
);
|
|
106
|
+
|
|
107
|
+
reportWebVitals();
|
|
108
|
+
defineCustomElements();
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
3. In your global css file (usually `App.css`) import the tegel stylesheet.
|
|
112
|
+
|
|
113
|
+
```css
|
|
114
|
+
@import url('@scania/tegel/dist/tegel/tegel.css');
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Angular
|
|
118
|
+
|
|
119
|
+
1. Run `npm install @scania/tegel`
|
|
120
|
+
2. In your `main.ts` import and call the function `defineCustomElements()`:
|
|
121
|
+
|
|
122
|
+
```ts
|
|
123
|
+
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';
|
|
124
|
+
import { defineCustomElements } from '@scania/tegel/loader';
|
|
125
|
+
import { AppModule } from './app/app.module';
|
|
126
|
+
|
|
127
|
+
platformBrowserDynamic()
|
|
128
|
+
.bootstrapModule(AppModule)
|
|
129
|
+
.catch((err) => console.error(err));
|
|
130
|
+
|
|
131
|
+
defineCustomElements(window);
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
3. In your `app.module.ts` import `CUSTOM_ELEMENTS_SCHEMA`:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
import { BrowserModule } from '@angular/platform-browser';
|
|
138
|
+
import { AppComponent } from './app.component';
|
|
139
|
+
|
|
140
|
+
@NgModule({
|
|
141
|
+
declarations: [AppComponent],
|
|
142
|
+
imports: [BrowserModule],
|
|
143
|
+
providers: [],
|
|
144
|
+
bootstrap: [AppComponent],
|
|
145
|
+
schemas: [CUSTOM_ELEMENTS_SCHEMA],
|
|
146
|
+
})
|
|
147
|
+
export class AppModule {}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
4. In your global css file (`styles.css`) import the tegel stylesheet.
|
|
151
|
+
|
|
152
|
+
```css
|
|
153
|
+
@import url('@scania/tegel/dist/tegel/tegel.css');
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
### HTML
|
|
157
|
+
|
|
158
|
+
1. Run `npm init` to generate a package.json
|
|
159
|
+
2. Run `npm install @scania/tegel`
|
|
160
|
+
3. Import the package and its style in your `<head>`:
|
|
161
|
+
|
|
162
|
+
```html
|
|
163
|
+
<script type="module">
|
|
164
|
+
import { defineCustomElements } from './node_modules/@scania/tegel/loader/index.es2017.js';
|
|
165
|
+
defineCustomElements();
|
|
166
|
+
</script>
|
|
167
|
+
<link rel="stylesheet" href="./node_modules/@scania/tegel/dist/tegel/tegel.css" />
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
See all available components in the [Tegel Design System](https://tegel.scania.com/components/overview).
|
|
171
|
+
|
|
172
|
+
## Events
|
|
173
|
+
|
|
174
|
+
The tegel components emit custom events to allow the users to repond to changes/updates in the components. These are all named using the
|
|
175
|
+
sdds-prefix. This is done in order to not have conflicting events and to make it clear to the user the specified event is something that is emitted
|
|
176
|
+
from a tegel component.
|
|
177
|
+
|
|
178
|
+
The events are named according to our naming convention: 'sdds' + event.
|
|
179
|
+
For a click event this would result in the event being called `sddsClick`. To listen for these events in vanilla JS the event name
|
|
180
|
+
should be passed to the `addEventListener` function as the first argument:
|
|
181
|
+
|
|
182
|
+
```javascript
|
|
183
|
+
document.addEventListener('sddsClick', (event) => {
|
|
184
|
+
// Do something with/based on the event.
|
|
185
|
+
});
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
In React these events needs to be listened to by adding an event listener to the element that emits the event. This can be easily done by
|
|
189
|
+
grabbing a reference to the element and adding the event listener inline:
|
|
190
|
+
|
|
191
|
+
This solution is a workaround based on how React handles events, you can read more on this [here.](https://reactjs.org/docs/events.html)
|
|
192
|
+
|
|
193
|
+
```jsx
|
|
194
|
+
<sdds-textfield
|
|
195
|
+
ref={(element) =>
|
|
196
|
+
element.addEventListener('sddsClick', (event) => {
|
|
197
|
+
{
|
|
198
|
+
/* Do something with/based on the event. */
|
|
199
|
+
}
|
|
200
|
+
})
|
|
201
|
+
}
|
|
202
|
+
></sdds-textfield>
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
In other JSX-enviroments (apart from React) these events can be listened to by prefixing them with an `on` directly on the component:
|
|
206
|
+
|
|
207
|
+
```jsx
|
|
208
|
+
<sdds-textfield
|
|
209
|
+
onSddsChange={(event) => {
|
|
210
|
+
/* Do something with/based on the event. */
|
|
211
|
+
}}
|
|
212
|
+
></sdds-textfield>
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
What is attached to the event object is highlighted in our storybook. Under the docs tab of each component the events are outlined,
|
|
216
|
+
inluding what data is passed with the event to the user.
|
|
217
|
+
|
|
218
|
+
### Internal events
|
|
219
|
+
|
|
220
|
+
Some of the component are using event to communicate with its parent/child. These events are not recommended to use in any way since
|
|
221
|
+
they might change without notice. Their payload might also be changed based on refactoring of components. These events are prefixed
|
|
222
|
+
with 'internal'. This is to make it as clear as possible to a user that this is an internal event that the components are using,
|
|
223
|
+
but the user should not interact with it. E.g. `internalSddsPropsChange`.
|
|
224
|
+
|
|
225
|
+
## Browser support
|
|
226
|
+
|
|
227
|
+
See the browser support section on [the Tegel website](https://tegel.scania.com/development/getting-started-development/introduction#browser-support).
|
|
228
|
+
|
|
229
|
+
## Code conventions
|
|
230
|
+
|
|
231
|
+
The code conventions used in (and enforced by) Tegel is documented [here](https://github.com/scania-digital-design-system/tegel/blob/main/.github/CODE_STYLE.md).
|
|
232
|
+
|
|
233
|
+
### Setting up the development environment
|
|
234
|
+
|
|
235
|
+
1. Make sure you are using the required node.js version specified in `tegel/package.json` (node 16 at the time of writing).
|
|
236
|
+
2. Run `npm install` in the root directory.
|
|
237
|
+
3. Run `npm install` in the core directory.
|
|
238
|
+
3. Create a `.env` file in the /tegel directory with the following contents:
|
|
239
|
+
|
|
240
|
+
```
|
|
241
|
+
STORYBOOK_ENV=development
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
4. Make sure you are in the root directory, and start the dev server with `npm run storybook`.
|
|
245
|
+
|
|
246
|
+
## Community
|
|
247
|
+
|
|
248
|
+
Get in touch with the team and the community:
|
|
249
|
+
|
|
250
|
+
- [Teams](https://teams.microsoft.com/l/team/19%3a1257007a64d44c64954acca27a9d4b46%40thread.skype/conversations?groupId=79f9bfeb-73e2-424d-9477-b236191ece5e&tenantId=3bc062e4-ac9d-4c17-b4dd-3aad637ff1ac)
|
|
251
|
+
|
|
252
|
+
## License
|
|
253
|
+
|
|
254
|
+
All CSS, HTML and JS code are available under the MIT license. The Scania brand identity, logos and photographs found in this repository are copyrighted Scania CV AB and are not available on an open source basis or to be used as examples or in any other way, if not specifically ordered by Scania CV AB.
|
|
@@ -225,7 +225,7 @@ export class Table {
|
|
|
225
225
|
"references": {
|
|
226
226
|
"InternalSddsTablePropChange": {
|
|
227
227
|
"location": "local",
|
|
228
|
-
"path": "/Users/
|
|
228
|
+
"path": "/Users/tro4zf/Projects/tegel/core/src/components/data-table/table/table.tsx"
|
|
229
229
|
}
|
|
230
230
|
}
|
|
231
231
|
}
|
|
@@ -189,7 +189,7 @@ export class SddsSideMenu {
|
|
|
189
189
|
"references": {
|
|
190
190
|
"CollapseEvent": {
|
|
191
191
|
"location": "local",
|
|
192
|
-
"path": "/Users/
|
|
192
|
+
"path": "/Users/tro4zf/Projects/tegel/core/src/components/side-menu/webcomponent/side-menu.tsx"
|
|
193
193
|
}
|
|
194
194
|
}
|
|
195
195
|
}
|
|
@@ -212,7 +212,7 @@ export class SddsSideMenu {
|
|
|
212
212
|
"references": {
|
|
213
213
|
"CollapseEvent": {
|
|
214
214
|
"location": "local",
|
|
215
|
-
"path": "/Users/
|
|
215
|
+
"path": "/Users/tro4zf/Projects/tegel/core/src/components/side-menu/webcomponent/side-menu.tsx"
|
|
216
216
|
}
|
|
217
217
|
}
|
|
218
218
|
}
|
|
@@ -235,7 +235,7 @@ export class SddsSideMenu {
|
|
|
235
235
|
"references": {
|
|
236
236
|
"InternalSddsSideMenuPropChange": {
|
|
237
237
|
"location": "local",
|
|
238
|
-
"path": "/Users/
|
|
238
|
+
"path": "/Users/tro4zf/Projects/tegel/core/src/components/side-menu/webcomponent/side-menu.tsx"
|
|
239
239
|
}
|
|
240
240
|
}
|
|
241
241
|
}
|
|
@@ -168,7 +168,7 @@ export class SddsStepper {
|
|
|
168
168
|
"references": {
|
|
169
169
|
"InternalSddsStepperPropChange": {
|
|
170
170
|
"location": "local",
|
|
171
|
-
"path": "/Users/
|
|
171
|
+
"path": "/Users/tro4zf/Projects/tegel/core/src/components/stepper/sdds-stepper.tsx"
|
|
172
172
|
}
|
|
173
173
|
}
|
|
174
174
|
}
|