Skip to content

Commit

Permalink
docs(readme): remove redundant sections, fix broken link (#11530)
Browse files Browse the repository at this point in the history 
## Summary

- Refer to the documentation site's get started page for all of the NPM
package usage instructions.
- Fix a broken link to the contributing documentation, which was moved
to the root directory of the monorepo.
- Change `Calcite Components` to `Calcite components`
- Cleanup the react wrapper package's readme

---------

Co-authored-by: Kitty Hurley <[email protected]>
  • Loading branch information
@benelan @geospatialem
benelan and geospatialem authored Feb 18, 2025
1 parent ce3e7d2 commit 54d5454
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 58 deletions.
38 changes: 15 additions & 23 deletions packages/calcite-components-react/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,30 @@
# Calcite Components React

A set of React components that wrap [Calcite Components](https://developers.arcgis.com/calcite-design-system/components/). An application using this package is provided in the [`calcite-components-examples`](https://github.com/Esri/calcite-components-examples) repo.
This package provides React wrappers for [Calcite components](https://developers.arcgis.com/calcite-design-system/components/). Refer to the [React example](https://github.com/Esri/calcite-design-system/tree/dev/examples/components/react) for a minimal application using this package.

## Installation

```sh
npm install --save @esri/calcite-components-react
npm install @esri/calcite-components-react
```

This package includes the compatible version of the main component library as a dependency, so no need to install `@esri/calcite-components` separately.
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 that are provided by the standard `calcite-components` package.
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 `calcite-components` assets. You can either use local assets, which will be explained in a subsequent step, or assets hosted on a CDN.
[Custom Elements](developers.arcgis.com/calcite-design-system/get-started#custom-elements) is the recommended build when using frontend frameworks, such as React. Assets from the CDN are used by default, but you can specify a local asset path with `setAssetPath`. Additional setup for using local assets will be explained in a subsequent step.

```jsx
import { setAssetPath } from "@esri/calcite-components/dist/components";
// Local assets
setAssetPath(window.location.href);
import { setAssetPath } from "@esri/calcite-components";

// CDN hosted assets
// setAssetPath("https://unpkg.com/@esri/calcite-components/dist/calcite/assets");
setAssetPath(window.location.href);
```

Next, you need to import each component you use from the standard `calcite-component` package's custom elements build. This will automatically define the custom elements on the window. Then import the same components from `calcite-components-react`.
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";
Expand All @@ -38,20 +35,15 @@ import { CalciteButton, CalciteIcon, CalciteSlider } from "@esri/calcite-compone

### Dist build

When using the [Dist](developers.arcgis.com/calcite-design-system/get-started#distribution) build, you'll need to manually define the custom elements on the window. You can also choose between local and CDN hosted assets.
When using the [Dist](developers.arcgis.com/calcite-design-system/get-started#distribution) build, you'll need to manually define the custom elements on the window:

```jsx
import { defineCustomElements } from "@esri/calcite-components/dist/loader";
// Local assets
defineCustomElements(window);

// CDN hosted assets
// defineCustomElements(window, {
// resourcesUrl: "https://unpkg.com/@esri/calcite-components/dist/calcite/assets"
// });
defineCustomElements();
```

Since you manually defined the custom elements on the window, you only need to import the individual components from `calcite-components-react`.
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";
Expand All @@ -75,7 +67,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:
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);
Expand All @@ -85,7 +77,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 / numbers
// 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(
(_) => {
Expand All @@ -95,7 +87,7 @@ useEffect(
);
```

Using `calcite-components-react`, these events are connected for you:
Using `@esri/calcite-components-react`, these events are connected for you:

```jsx
const [sliderValue, setSliderValue] = useState(50);
Expand All @@ -106,7 +98,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 main [calcite-components CONTRIBUTING.md](../../../../CONTRIBUTING.md) for an overview of contribution guidelines.
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

Expand Down
42 changes: 7 additions & 35 deletions packages/calcite-components/readme.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@
[![downloads per month](https://img.shields.io/npm/dm/@esri/calcite-components?style=flat-square&color=35AC46)](https://www.npmjs.com/package/@esri/calcite-components)
[![commits per month](https://img.shields.io/github/commit-activity/m/esri/calcite-components?style=flat-square&color=EDD317)](https://github.com/Esri/calcite-design-system/graphs/contributors)

# Calcite Components
# Calcite components

Calcite Components, part of Esri's Calcite Design System, is a rich library of flexible, framework-agnostic web components for building applications. View the [documentation](https://developers.arcgis.com/calcite-design-system/components/) for component descriptions, examples, and API reference, which includes properties, slots, styles, and theming.
Calcite components, part of Esri's Calcite Design System, is a rich library of flexible, framework-agnostic web components for building applications. View the [documentation](https://developers.arcgis.com/calcite-design-system/components/) for component descriptions, examples, and API reference, which includes properties, slots, styles, and theming.

## Use the CDN

The most common approach for loading Calcite Components is to use the version hosted on the CDN. The components can be loaded via `<script>` and `<link>` tags in the head of your HTML document:
The most common approach for loading Calcite components is to use the version hosted on the CDN. The components can be loaded via `<script>` and `<link>` tags in the head of your HTML document:

<!-- x-release-please-start-version -->

Expand All @@ -32,41 +32,13 @@ Once these tags are added, components can be used like any other HTML element. O

## Use the NPM package

Calcite Components is also provided as an [NPM package](https://www.npmjs.com/package/@esri/calcite-components). To get started, first install the package, then follow the steps below. Alternatively, you can find examples using different frameworks and build tools [here](https://github.com/Esri/calcite-components-examples).

```sh
npm install @esri/calcite-components
```

### 1. Build

Refer to the [Get started](https://developers.arcgis.com/calcite-design-system/get-started/) page for details on setting up a build.

### 2. Assets

Some components, such as `calcite-icon` and `calcite-date-picker`, rely on assets being available at a particular path. As mentioned, with the NPM package you have the option to provide a local path or the URL to the assets hosted on the CDN. Using the CDN hosted assets can help decrease on disk build size.

To use the assets locally, they need to be copied using a build tool or NPM script. The directory for the local assets must be named `assets`, which eases the copying process. For example, `/public/calcite/assets` will work, however `/public/calcite-assets` will not.

The Calcite Components [examples repo](https://github.com/Esri/calcite-components-examples) demonstrates using local assets in a variety of JavaScript frameworks and build tools. Each example has a README with a framework or build tool specific explanation.

```sh
cp -r node_modules/@esri/calcite-components/dist/calcite/assets/* ./public/assets/
```

### 3. Styles

Finally, load the Cascading Style Sheet (CSS). This is also dependent on your framework or build tool, however in many cases it can be imported in JavaScript:

```js
import "@esri/calcite-components/dist/calcite/calcite.css";
```
Refer to the [Get started](https://developers.arcgis.com/calcite-design-system/get-started/#use-the-npm-package) page for details on setting up the [NPM package](https://www.npmjs.com/package/@esri/calcite-components).

## TypeScript

Refer to the [TypeScript section of the Framework integration](https://developers.arcgis.com/calcite-design-system/resources/frameworks/#typescript) resource page for guidance on setting up TypeScript.
Refer to the [Framework integration](https://developers.arcgis.com/calcite-design-system/resources/frameworks/#typescript) resource page for guidance on setting up TypeScript.

## Browser Support
## Browser support

<table>
<thead>
Expand All @@ -86,7 +58,7 @@ Refer to the [TypeScript section of the Framework integration](https://developer

## Contributing

We welcome contributions to this project. See [CONTRIBUTING.md](./CONTRIBUTING.md) for an overview of contribution guidelines.
We welcome contributions to this project. See [CONTRIBUTING.md](https://github.com/Esri/calcite-design-system/blob/dev/CONTRIBUTING.md) for an overview of contribution guidelines.

## License

Expand Down

0 comments on commit 54d5454

Please sign in to comment.