npm - @dxos/react-ui - Versions diffs - 0.1.20 → 0.1.21 - Mend

@dxos/react-ui 0.1.20 → 0.1.21

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.

Files changed (331) hide show

package/README.md CHANGED Viewed

@@ -1,146 +1,22 @@
-# DXOS design system
+# @dxos/react-ui
-The `react-ui` package is the single source of truth for DXOS’s design system.
+A React component library for DXOS’s OS experiences
-To get started, you’ll need to add the build plugin (Vite or ESBuild), then set up the provider, then set up theming.
+## Installation
-## How to use with Vite
-Using the design system requires opting-in in a few places, but by design it
-otherwise needs no configuration.
-### 1. Add the Vite plugin
-Add `@dxos/react-ui` to the project’s dev dependencies, then extend the
-project’s Vite config to use it, e.g.:
-```ts
-// ...
-import { ThemePlugin } from '@dxos/react-ui/plugin';
-// ...
-export default defineConfig({
-  // ...
-  plugins: [
-    // ...
-    ThemePlugin({content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}']}),
-    // ...
-  ]
-  // ...
-});
-// ...
-```
-Ensure `content` contains globs for your project’s own files that will use Tailwind classnames, as well as any DXOS
-design system packages your project uses, e.g.:
-```
-'./node_modules/@dxos/react-ui/dist/**/*.mjs',
-'./node_modules/@dxos/react-uikit/dist/**/*.mjs',
-'./node_modules/@dxos/react-appkit/dist/**/*.mjs',
-'./node_modules/@dxos/react-composer/dist/**/*.mjs',
+```bash
+pnpm i @dxos/react-ui
 ```
-### 2. Reference the basic stylesheet
-In the file which calls React DOM’s `createRoot` or `render`, add:
-```ts
-import '@dxosTheme';
-```
-### Done
-Now you can use Tailwind utility classnames in your project.
-## How to use with ESBuild
-The ESBuild plugin is experimental and has several caveats noted below, proceed with caution.
-### 1. Add the ESBuild plugin
-Add `@dxos/react-ui` to the project’s dev dependencies, then extend the
-project’s ESBuild config to use it, e.g.:
-```ts
-// ...
-import { ThemePlugins } from '@dxos/react-ui/esbuild-plugin';
-// ...
-void build({
-  entryPoints: [/* ... */, resolve(__dirname, '../node_modules/@dxos/react-ui/src/theme.css')],
-  // ...
-  plugins: ThemePlugins({
-    outdir: resolve(__dirname, '../dist'),
-    content: [
-      resolve(__dirname, '../index.html'),
-      resolve(__dirname, '../src/**/*.{js,ts,jsx,tsx}'),
-      resolve(__dirname, '../node_modules/@dxos/react-ui/dist/**/*.mjs')
-      // other sources to scan
-    ]
-  })
-});
-// ...
-```
+## DXOS Resources
-Ensure `theme.css` from `react-ui` is included as an entrypoint, and `outdir` passed to `ThemePlugins` is the same as
-provided to ESBuild.
+- [Website](https://dxos.org)
+- [Developer Documentation](https://docs.dxos.org)
+- Tag [questions on Stack Overflow](https://stackoverflow.com/questions/tagged/dxos) with `#dxos`
+- Tag us on twitter [`@dxos_org`](https://twitter.com/dxos_org)
-### 2. Reference the basic stylesheet
-Load the built stylesheet as appropriate for your project, e.g. simply add it to `index.html`:
-```html
-<link rel="stylesheet" href="./dist/node_modules/@dxos/react-ui/src/theme.css"/>
-```
-Note that _this is not in your project’s node_modules directory_, it’s in your project’s `outdir`.
-### Done
-Now you can use Tailwind utility classnames in your project.
-## Set up the provider
-In order for the project to render correctly, wrap your app with `<UiKitProvider/>` if your project uses `react-uikit`,
-or `<UiProvider/>` if your project only uses this package. Don’t use both, since the former already includes the latter.
-## Set up theming
-In order to display the correct theme, you need to mark `<html>` with the correct class _from the `<head>` tag_, otherwise it will flash the wrong theme:
-```html
-<head>
-  <script>
-    if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
-      document.documentElement.classList.add('dark')
-    } else {
-      document.documentElement.classList.remove('dark')
-    }
-  </script>
-</head>
-```
-If you want to keep up with `prevers-color-scheme`, add:
-```js
-window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function(e){ if(e.matches){
-  document.documentElement.classList.add('dark')
-} else {
-  document.documentElement.classList.remove('dark')
-}})
-```
-You could combine the two with a script like this one:
-```js
-function setTheme(darkMode) {
-  document.documentElement.classList[darkMode ? 'add' : 'remove']('dark')
-}
-setTheme(window.matchMedia('(prefers-color-scheme: dark)').matches)
-window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', function (e) {
-  setTheme(e.matches)
-});
-```
+## Contributions
-You can augment this predicate checking any preferences saved in `localStorage`, etc.
+Your ideas, issues, and code are most welcome. Please take a look at our [community code of conduct](https://github.com/dxos/dxos/blob/main/CODE_OF_CONDUCT.md), the [issue guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-issues), and the [PR contribution guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md#submitting-prs). If you would like to contribute to the design and implementation of DXOS, please [start with the contributor's guide](https://github.com/dxos/dxos/blob/main/CONTRIBUTING.md).
-Note that you can apply this classname selectively further down the DOM tree if needed.
+License: [MIT](./LICENSE) Copyright 2022 © DXOS