docs(readme): remove redundant sections, fix broken link #11530
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -1,22 +1,22 @@ | ||||||
| # Calcite Components React | ||||||
|
|
||||||
| This package provides React wrappers for [Calcite components](https://developers.arcgis.com/calcite-design-system/components/). See the [react example](https://github.com/Esri/calcite-design-system/tree/dev/examples/components/react) for a minimal application using this package. | ||||||
benelan marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| ## Installation | ||||||
|
|
||||||
| ```sh | ||||||
| npm install --save @esri/calcite-components-react | ||||||
| ``` | ||||||
|
|
||||||
| This package includes the compatible version of the standard `@esri/calcite-components` package, so you do not need to install it separately. | ||||||
|
|
||||||
| ## Choose a build | ||||||
|
|
||||||
| There are two builds provided by the standard components package. | ||||||
|
|
||||||
| ### Custom Elements build | ||||||
|
|
||||||
| [Custom Elements](developers.arcgis.com/calcite-design-system/get-started#custom-elements) is the recommended build when using frontend frameworks, such as React. To use this build, you will need to set the path to the components assets. You can either use local assets, which will be explained in a subsequent step, or assets hosted on a CDN. | ||||||
|
|
||||||
| ```jsx | ||||||
| import { setAssetPath } from "@esri/calcite-components/dist/components"; | ||||||
|
There was a problem hiding this comment. Would the commented out There was a problem hiding this comment. I think it's fine as it is because it's where React apps commonly serve their assets, e.g. our React example: It's generalized in the doc because it's not the same for all frameworks or build tools, e.g. our rollup example: There was a problem hiding this comment. I guess we could remove the commented snippet for CDN assets though because I think Lumina uses the CDN by default when There was a problem hiding this comment. @maxpatiiuk is that correct? And is there a new default behavior for There was a problem hiding this comment.
Correct. in map-components 4.32 we only document setAssetPath for people who don't want to use our CDN/need offline deployment There was a problem hiding this comment. Yes, defineCustomElements has the same behaviour There was a problem hiding this comment. The path can be simplified:
Suggested change
|
||||||
|
|
@@ -27,7 +27,7 @@ setAssetPath(window.location.href); | |||||
| // setAssetPath("https://unpkg.com/@esri/calcite-components/dist/calcite/assets"); | ||||||
| ``` | ||||||
|
|
||||||
| Next, you need to import each component you use from the standard components package's custom elements build. This will automatically define the custom elements on the window. Then, import the same components from `@esri/calcite-components-react`. | ||||||
|
|
||||||
| ```jsx | ||||||
| import "@esri/calcite-components/dist/components/calcite-button"; | ||||||
|
|
@@ -51,7 +51,7 @@ defineCustomElements(window); | |||||
| // }); | ||||||
| ``` | ||||||
|
|
||||||
| Since you manually defined the custom elements on the window, you only need to import the individual components from `@esri/calcite-components-react`. | ||||||
|
|
||||||
| ```jsx | ||||||
| import { CalciteButton, CalciteIcon, CalciteSlider } from "@esri/calcite-components-react"; | ||||||
|
|
@@ -75,7 +75,7 @@ cp -r node_modules/@esri/calcite-components/dist/calcite/assets/* ./public/asset | |||||
|
|
||||||
| ## Why not just use the web components directly? | ||||||
|
|
||||||
| Because React uses a synthetic event system, the custom events emitted from Calcite components won't work with JSX in React. For example, say you want to update some value when the `calcite-slider` component changes. When using the standard web components, you need to save a ref to the element, and add a listener: | ||||||
|
|
||||||
| ```jsx | ||||||
| const sliderEl = useRef(null); | ||||||
|
|
@@ -85,7 +85,7 @@ function onUpdate(event) { | |||||
| setSliderValue(event.target.value); | ||||||
| } | ||||||
|
|
||||||
| // need to access the DOM node to set custom event listeners for props that aren't strings or numbers | ||||||
| // lit.dev/docs/frameworks/react#why-are-wrappers-needed | ||||||
| useEffect( | ||||||
| (_) => { | ||||||
|
|
@@ -95,7 +95,7 @@ useEffect( | |||||
| ); | ||||||
| ``` | ||||||
|
|
||||||
| Using `@esri/calcite-components-react`, these events are connected for you: | ||||||
|
|
||||||
| ```jsx | ||||||
| const [sliderValue, setSliderValue] = useState(50); | ||||||
|
|
@@ -106,7 +106,7 @@ If you're using TypeScript, you'll also get increased type safety for your event | |||||
|
|
||||||
| ## Contributing | ||||||
|
|
||||||
| We welcome contributions to this project. See the [CONTRIBUTING.md](https://github.com/Esri/calcite-design-system/blob/dev/CONTRIBUTING.md) for an overview of contribution guidelines. | ||||||
|
|
||||||
| ## License | ||||||
|
|
||||||
|
|
||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
With Lumina, you are now also providing JSX typings for React 19 users.
Given that more and more people will be shifting to React 19, it would be ideal to point out on this page or somewhere else that wrappers are not required in React 19 (but still supported).
documentation on usage in React in https://qawebgis.esri.com/components/lumina/publishing#using-the-npm-package (generally same as other frameworks, except for need to add a specific /// directive to get the JSX typings)