@openfin/ui-library 0.0.0-alpha.20251106191835.d80a1d5
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/LICENSE.md +5 -0
- package/README.md +213 -0
- package/package.json +175 -0
package/LICENSE.md
ADDED
package/README.md
ADDED
|
@@ -0,0 +1,213 @@
|
|
|
1
|
+
# @openfin/ui-library
|
|
2
|
+
|
|
3
|
+
A React component library for OpenFin applications.
|
|
4
|
+
|
|
5
|
+
**Storybook:** [cdn.openfin.co/workspace/storybook](https://cdn.openfin.co/workspace/storybook)
|
|
6
|
+
**NPM Package:** [@openfin/ui-library](https://www.npmjs.com/package/@openfin/ui-library)
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## What is this for?
|
|
11
|
+
|
|
12
|
+
**TL;DR** – Use this library and write less CSS.
|
|
13
|
+
|
|
14
|
+
This is an opinionated React component library, built on top of [styled-components](https://styled-components.com/docs), which aims to provide the basic building blocks that you can use in any OpenFin environment. It was built w/ our [Spatial Design System](https://www.figma.com/file/0Y3pKZj0tJWuleF12h5Sua/Spatial---Components) in mind, so it should always reflect OpenFin's latest branding and designs.
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
### 1. Make sure you have @openfin NPM access
|
|
19
|
+
|
|
20
|
+
- Make sure you have @openfin private NPM registry access
|
|
21
|
+
- Log in to npm, preferably via `npm login`.
|
|
22
|
+
|
|
23
|
+
### 2. Install the package
|
|
24
|
+
|
|
25
|
+
…along with `styled-components`.
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# Install the latest version
|
|
29
|
+
$ yarn add @openfin/ui-library styled-components
|
|
30
|
+
# For npm
|
|
31
|
+
$ npm i @openfin/ui-library styled-components
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# Install a specific version
|
|
36
|
+
$ yarn add @openfin/ui-library@v0.8.0
|
|
37
|
+
# For npm
|
|
38
|
+
$ npm i @openfin/ui-library@0.8.0
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Usage
|
|
42
|
+
|
|
43
|
+
### ThemeProvider
|
|
44
|
+
|
|
45
|
+
`ThemeProvider` is the component that provides theme information to the `ui-library` components nested deeply within your application. Make sure to include this above your application so your components will be styled properly.
|
|
46
|
+
|
|
47
|
+
```javascript
|
|
48
|
+
import { ThemeProvider } from '@openfin/ui-library';
|
|
49
|
+
import MyApp from 'some/cool/place';
|
|
50
|
+
|
|
51
|
+
const MyCoolAppContainer = () => (
|
|
52
|
+
<ThemeProvider>
|
|
53
|
+
<MyApp />
|
|
54
|
+
</ThemeProvider>
|
|
55
|
+
);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Basic Usage
|
|
59
|
+
|
|
60
|
+
```javascript
|
|
61
|
+
import { Box, H1, Icon, TextInput } from '@openfin/ui-library';
|
|
62
|
+
|
|
63
|
+
export const MyApp = () => (
|
|
64
|
+
<Box flexDirection="column">
|
|
65
|
+
<H1>
|
|
66
|
+
<Icon icon="OpenFinIcon" /> Cool heading
|
|
67
|
+
</H1>
|
|
68
|
+
|
|
69
|
+
<TextInput placeholder="Cool stuff goes here" />
|
|
70
|
+
</Box>
|
|
71
|
+
);
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
**View the [Full Component Docs](./src/components) for more usage info.**
|
|
75
|
+
|
|
76
|
+
### Extending Components
|
|
77
|
+
|
|
78
|
+
Whenever possible, it is prefereable to use the components as-is. However – using [styled-components](https://styled-components.com/docs), it is very easy. Try using the following guiding principles when doing so:
|
|
79
|
+
|
|
80
|
+
- Familiarize yourself w/ the `theme` prop, and use it whenever possible.
|
|
81
|
+
- Avoid hard-coded pixel values.
|
|
82
|
+
- Don't _ever_ use hard-coded color values.
|
|
83
|
+
|
|
84
|
+
```javascript
|
|
85
|
+
import { Box, Text } from '@openfin/ui-library';
|
|
86
|
+
import styled from 'styled-components';
|
|
87
|
+
|
|
88
|
+
export const MyCoolComponent = () => (
|
|
89
|
+
<Container flexDirection="column">
|
|
90
|
+
<ImportantText>How cool is this?</ImportantText>
|
|
91
|
+
<Text weight="bold">Super cool</Text>
|
|
92
|
+
</Container>
|
|
93
|
+
);
|
|
94
|
+
|
|
95
|
+
const Container = styled(Box)`
|
|
96
|
+
background: ${({ theme }) => theme.palette.background6};
|
|
97
|
+
border-radius: ${({ theme }) => theme.radius.small};
|
|
98
|
+
margin: ${({ theme }) => `${theme.px.small} 0 ${theme.px.base}`};
|
|
99
|
+
`;
|
|
100
|
+
|
|
101
|
+
const ImportantText = styled(Text)`
|
|
102
|
+
color: ${({ theme }) => theme.palette.statusWarning};
|
|
103
|
+
cursor: pointer;
|
|
104
|
+
font-weight: ${({ theme }) => theme.fontWeight.bold};
|
|
105
|
+
`;
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Contributing
|
|
109
|
+
|
|
110
|
+
### Open a pull request 😎
|
|
111
|
+
|
|
112
|
+
Pull requests are a great way to express an idea or need, if it's easier to "show" instead of "tell", go for it, propose a change!
|
|
113
|
+
|
|
114
|
+
Also keep in mind, UI Library is a home of centralized common components, **used by several products**. It's reasonable to expect PRs may spark conversations about the **essence of the change** and it's benefits and impact across the application ecosystem.
|
|
115
|
+
|
|
116
|
+
Meaning: While there are no hard rules about what belongs in _our_ library, if a change is too opinionated or too specialized, it may make sense to leave it out. **A library that does less, is a lot easier to know and work with**.
|
|
117
|
+
|
|
118
|
+
**Please be sure to update the package version before submitting your pull request.** If you are unsure what the new verison should be, please refer to [Semantic Versioning](https://semver.org/).
|
|
119
|
+
|
|
120
|
+
### Storybook
|
|
121
|
+
|
|
122
|
+
Great for exploring and experimenting with UI Library components. It's also used for [testing our components](https://storybook.js.org/docs/react/workflows/unit-testing).
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
# Run it locally
|
|
126
|
+
$ npm run storybook
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Codesandbox.io
|
|
130
|
+
|
|
131
|
+
Great for developer experimentation without all of the overhead.
|
|
132
|
+
|
|
133
|
+
The sandbox is currently **private**, request access and [give it a try](https://codesandbox.io/s/openfin-ui-library-39y7c).
|
|
134
|
+
|
|
135
|
+
### Working locally w/ other apps
|
|
136
|
+
|
|
137
|
+
Sometimes you may need to work on the `ui-library` alongside your own application. We use [yalc](https://www.npmjs.com/package/yalc) for this. It solves a few problems that `yarn link` creates, and it's pretty intuitive.
|
|
138
|
+
|
|
139
|
+
#### 1. Install and setup yalc
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
# Make sure yalc is installed globally
|
|
143
|
+
$ npm i yalc -g
|
|
144
|
+
|
|
145
|
+
# Set up yalc in ui-library
|
|
146
|
+
$ cd ui-library/
|
|
147
|
+
$ yalc publish
|
|
148
|
+
|
|
149
|
+
# Add local ui-library package to your app
|
|
150
|
+
$ cd ../myCoolApp/
|
|
151
|
+
$ yalc add @openfin/ui-library
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
This links your local copy of UI Library to your app using symlinks and `package.json`.
|
|
155
|
+
|
|
156
|
+
#### 2. Working with yalc
|
|
157
|
+
|
|
158
|
+
Once you're setup, subsequent changes in UI Library can be propagated across easily.
|
|
159
|
+
|
|
160
|
+
After making changes in `ui-library`, run `npm run build && yalc push`. This will apply a version bump to the local yalc package respository. It will also update the package in your app directory, but you will most likely need to restart any development servers to see the changes.
|
|
161
|
+
|
|
162
|
+
```sh
|
|
163
|
+
# push updates from ui-library side to your app
|
|
164
|
+
$ npm run build && yalc push --sig
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
#### Known Issues
|
|
168
|
+
|
|
169
|
+
- Storybook does not pick up changes after a `yalc push` and must be restarted
|
|
170
|
+
|
|
171
|
+
## Compiling the Library
|
|
172
|
+
|
|
173
|
+
### `tsonfig.json`
|
|
174
|
+
|
|
175
|
+
The base Typescript config.
|
|
176
|
+
|
|
177
|
+
### `tsonfig.bundle.json`
|
|
178
|
+
|
|
179
|
+
Extending base config used by `tsc` when bundling the library for a new release.
|
|
180
|
+
|
|
181
|
+
### `tsonfig.storybook.json`
|
|
182
|
+
|
|
183
|
+
Extending base config used by `Storybook` to quiet some extraneous warnings.
|
|
184
|
+
|
|
185
|
+
## Testing
|
|
186
|
+
|
|
187
|
+
```sh
|
|
188
|
+
npm run test
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Versioning & Releasing
|
|
192
|
+
|
|
193
|
+
### 1. Bump package version
|
|
194
|
+
|
|
195
|
+
Once you are ready to make a new release and all PRs meant for a release have been merged into `main` branch, you should now create a new branch to bump the package version (for example name the branch `<yourName>/bump-version/<new-version-number>`). Next, run `npm version [<newversion> | major | minor | patch]` to bump the package version. Now, create a PR into the `main` branch and get that PR approved and merged.
|
|
196
|
+
|
|
197
|
+
### 2. Create a release branch
|
|
198
|
+
|
|
199
|
+
Now that the package version is up to date, you should now create a new release branch in github. To do so, go to the [list of branches](https://github.com/openfin/ui-library/branches) and click 'New Branch.' Name the new branch `release/<new-version-number>` (for example `release/0.14.3`) and make sure the branch source is `main`.
|
|
200
|
+
|
|
201
|
+
### 3. Create a new release on Github
|
|
202
|
+
|
|
203
|
+
Once you have created the release branch, you should now create a release through github:
|
|
204
|
+
|
|
205
|
+
- Click [Create a New Release](https://github.com/openfin/ui-library/releases/new)
|
|
206
|
+
- Create a new tag, labelled `<new-version-number>`. (for example `0.14.3`)
|
|
207
|
+
- Change the target branch to the release branch you just created. (for example `release/0.14.3`)
|
|
208
|
+
- Enter the release title to match the tag you just created. (for example `0.14.3`)
|
|
209
|
+
- In the description, enter the changelog from the previous tag. (for example if previous tag is `0.14.2` then your description should be "Change log: `https://github.com/openfin/ui-library/compare/0.14.2...0.14.3`") (Don't worry, you can always go back and edit the description later.)
|
|
210
|
+
|
|
211
|
+
This triggers a Github Action to automatically build the latest version of the `ui-library` and package it for remote installation. You can check the status of this task within this repo's actions tab.
|
|
212
|
+
|
|
213
|
+
### 4. Create pull requests in both Workspace and Notifications to bump the UI-Library package to the latest version that you just released
|
package/package.json
ADDED
|
@@ -0,0 +1,175 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@openfin/ui-library",
|
|
3
|
+
"description": "OpenFin UI Component Library",
|
|
4
|
+
"version": "0.0.0-alpha.20251106191835.d80a1d5",
|
|
5
|
+
"main": "dist/index.js",
|
|
6
|
+
"types": "dist/index.d.ts",
|
|
7
|
+
"repository": {
|
|
8
|
+
"type": "git",
|
|
9
|
+
"url": "git+https://github.com/openfin/workspace.git",
|
|
10
|
+
"directory": "packages/ui-library"
|
|
11
|
+
},
|
|
12
|
+
"homepage": "https://cdn.openfin.co/workspace/storybook",
|
|
13
|
+
"files": [
|
|
14
|
+
"dist/**/*"
|
|
15
|
+
],
|
|
16
|
+
"exports": {
|
|
17
|
+
"./fonts/*": "./dist/assets/fonts/*",
|
|
18
|
+
".": {
|
|
19
|
+
"types": "./dist/index.d.ts",
|
|
20
|
+
"default": "./dist/index.js"
|
|
21
|
+
},
|
|
22
|
+
"./dist/theme": {
|
|
23
|
+
"types": "./dist/theme.d.ts",
|
|
24
|
+
"default": "./dist/theme.js"
|
|
25
|
+
}
|
|
26
|
+
},
|
|
27
|
+
"license": "SEE LICENSE IN LICENSE.MD",
|
|
28
|
+
"scripts": {
|
|
29
|
+
"start": "npm run storybook",
|
|
30
|
+
"dev": "webpack build --config webpack.config.js --mode development --watch",
|
|
31
|
+
"typecheck": "npx tsc --noEmit",
|
|
32
|
+
"build": "npm run build:clean && npm run build:scss && npm run build:src",
|
|
33
|
+
"build:src": "webpack build --config webpack.config.js --mode production",
|
|
34
|
+
"build:clean": "rimraf dist",
|
|
35
|
+
"build:scss": "sass src/styles:dist/styles",
|
|
36
|
+
"build:dev": "webpack build --config webpack.config.js --mode development && yalc push",
|
|
37
|
+
"build:watch": "webpack build --config webpack.config.js --mode development --watch",
|
|
38
|
+
"test:ci": "jest",
|
|
39
|
+
"test": "jest --watch",
|
|
40
|
+
"lint": "npm run lint:typescript && npm run lint:styles",
|
|
41
|
+
"lint:typescript": "eslint \"./src/**/*.{ts,tsx}\"",
|
|
42
|
+
"lint:styles": "stylelint \"./src/**/*.{ts,tsx}\"",
|
|
43
|
+
"storybook": "storybook dev -p 6006",
|
|
44
|
+
"storybook:build": "storybook build",
|
|
45
|
+
"storybook:cache-clear": "rimraf ./node_modules/.cache/storybook"
|
|
46
|
+
},
|
|
47
|
+
"peerDependencies": {
|
|
48
|
+
"@radix-ui/react-icons": ">=1.3.2 <2.0.0",
|
|
49
|
+
"framer-motion": ">=11.13.1 <12.0.0",
|
|
50
|
+
"react": ">=18.3.1 <19.0.0",
|
|
51
|
+
"react-calendar": ">=5.1.0 <6.0.0",
|
|
52
|
+
"react-dom": ">=18.3.1 <19.0.0",
|
|
53
|
+
"styled-components": ">=5.3.11 <6.0.0"
|
|
54
|
+
},
|
|
55
|
+
"dependencies": {
|
|
56
|
+
"focus-trap-react": "^9.0.2",
|
|
57
|
+
"lodash.merge": "^4.6.2",
|
|
58
|
+
"require-from-string": "^2.0.2",
|
|
59
|
+
"tinycolor2": "^1.6.0"
|
|
60
|
+
},
|
|
61
|
+
"devDependencies": {
|
|
62
|
+
"@babel/core": "^7.18.6",
|
|
63
|
+
"@babel/preset-env": "^7.28.3",
|
|
64
|
+
"@babel/preset-react": "^7.27.1",
|
|
65
|
+
"@babel/preset-typescript": "^7.27.1",
|
|
66
|
+
"@storybook/addon-actions": "^8.6.14",
|
|
67
|
+
"@storybook/addon-essentials": "^8.6.14",
|
|
68
|
+
"@storybook/addon-interactions": "^8.6.14",
|
|
69
|
+
"@storybook/addon-links": "^8.6.14",
|
|
70
|
+
"@storybook/node-logger": "^8.6.14",
|
|
71
|
+
"@storybook/react": "^8.6.14",
|
|
72
|
+
"@storybook/react-webpack5": "^8.6.14",
|
|
73
|
+
"@stylelint/postcss-css-in-js": "^0.38.0",
|
|
74
|
+
"@testing-library/dom": "^10.4.0",
|
|
75
|
+
"@testing-library/jest-dom": "^6.6.3",
|
|
76
|
+
"@testing-library/react": "^16.0.1",
|
|
77
|
+
"@testing-library/user-event": "^14.5.2",
|
|
78
|
+
"@types/jest": "^28.1.3",
|
|
79
|
+
"@types/lodash.merge": "^4.6.2",
|
|
80
|
+
"@types/node": "^18.15.12",
|
|
81
|
+
"@types/react": "18.3.24",
|
|
82
|
+
"@types/react-dom": "^18.3.1",
|
|
83
|
+
"@types/styled-components": "^5.1.34",
|
|
84
|
+
"@types/tinycolor2": "^1.4.6",
|
|
85
|
+
"@typescript-eslint/eslint-plugin": "5.62.0",
|
|
86
|
+
"@typescript-eslint/parser": "5.62.0",
|
|
87
|
+
"babel-loader": "^8.4.1",
|
|
88
|
+
"copy-webpack-plugin": "^11.0.0",
|
|
89
|
+
"cross-env": "^7.0.3",
|
|
90
|
+
"css-loader": "^6.11.0",
|
|
91
|
+
"eslint": "^8.40.0",
|
|
92
|
+
"eslint-config-prettier": "^8.8.0",
|
|
93
|
+
"eslint-plugin-jest": "^26.5.3",
|
|
94
|
+
"eslint-plugin-prettier": "^4.2.1",
|
|
95
|
+
"eslint-plugin-react": "^7.32.2",
|
|
96
|
+
"file-loader": "^6.2.0",
|
|
97
|
+
"identity-obj-proxy": "^3.0.0",
|
|
98
|
+
"jest": "^29.7.0",
|
|
99
|
+
"jest-environment-jsdom": "^29.7.0",
|
|
100
|
+
"jest-transform-stub": "^2.0.0",
|
|
101
|
+
"postcss-styled-syntax": "^0.4.0",
|
|
102
|
+
"prettier": "^2.8.8",
|
|
103
|
+
"react-docgen-typescript": "^2.4.0",
|
|
104
|
+
"react-is": "^17.0.2",
|
|
105
|
+
"react-refresh": "^0.14.0",
|
|
106
|
+
"resize-observer-polyfill": "^1.5.1",
|
|
107
|
+
"rimraf": "^5.0.0",
|
|
108
|
+
"sass": "^1.93.2",
|
|
109
|
+
"sass-loader": "^16.0.5",
|
|
110
|
+
"storybook": "^8.6.14",
|
|
111
|
+
"style-loader": "^4.0.0",
|
|
112
|
+
"stylelint": "^14.9.1",
|
|
113
|
+
"stylelint-config-recommended": "^8.0.0",
|
|
114
|
+
"stylelint-config-styled-components": "^0.1.1",
|
|
115
|
+
"stylelint-processor-styled-components": "^1.10.0",
|
|
116
|
+
"ts-jest": "^29.1.2",
|
|
117
|
+
"ts-loader": "^9.3.1",
|
|
118
|
+
"typescript": "5.1.3",
|
|
119
|
+
"webpack": "^5.82.1",
|
|
120
|
+
"webpack-bundle-analyzer": "4.10.2",
|
|
121
|
+
"webpack-cli": "^5.1.1"
|
|
122
|
+
},
|
|
123
|
+
"browserslist": {
|
|
124
|
+
"production": [
|
|
125
|
+
">0.2%",
|
|
126
|
+
"not dead",
|
|
127
|
+
"not op_mini all"
|
|
128
|
+
],
|
|
129
|
+
"development": [
|
|
130
|
+
"last 1 chrome version",
|
|
131
|
+
"last 1 firefox version",
|
|
132
|
+
"last 1 safari version"
|
|
133
|
+
]
|
|
134
|
+
},
|
|
135
|
+
"stylelint": {
|
|
136
|
+
"customSyntax": "@stylelint/postcss-css-in-js",
|
|
137
|
+
"extends": [
|
|
138
|
+
"stylelint-config-recommended"
|
|
139
|
+
],
|
|
140
|
+
"rules": {
|
|
141
|
+
"no-empty-source": null,
|
|
142
|
+
"function-no-unknown": null,
|
|
143
|
+
"no-extra-semicolons": null,
|
|
144
|
+
"unit-no-unknown": null
|
|
145
|
+
}
|
|
146
|
+
},
|
|
147
|
+
"prettier": {
|
|
148
|
+
"endOfLine": "lf",
|
|
149
|
+
"semi": true,
|
|
150
|
+
"singleQuote": true,
|
|
151
|
+
"tabWidth": 2,
|
|
152
|
+
"trailingComma": "es5",
|
|
153
|
+
"arrowParens": "always",
|
|
154
|
+
"printWidth": 100
|
|
155
|
+
},
|
|
156
|
+
"jest": {
|
|
157
|
+
"preset": "ts-jest",
|
|
158
|
+
"setupFilesAfterEnv": [
|
|
159
|
+
"<rootDir>/src/setupTests.ts"
|
|
160
|
+
],
|
|
161
|
+
"moduleNameMapper": {
|
|
162
|
+
"\\.(css)$": "<rootDir>/src/test/mocks/styleMock.js"
|
|
163
|
+
},
|
|
164
|
+
"transform": {
|
|
165
|
+
".+\\.(ttf|woff|woff2)$": "jest-transform-stub"
|
|
166
|
+
},
|
|
167
|
+
"testEnvironment": "jsdom",
|
|
168
|
+
"testMatch": [
|
|
169
|
+
"<rootDir>/src/**/*.test.tsx",
|
|
170
|
+
"<rootDir>/src/**/*.test.ts",
|
|
171
|
+
"<rootDir>/src/**/*.spec.ts",
|
|
172
|
+
"<rootDir>/src/**/*.spec.tsx"
|
|
173
|
+
]
|
|
174
|
+
}
|
|
175
|
+
}
|