From 8deef749996cc725b9e2d187bfd5c0c7414cef20 Mon Sep 17 00:00:00 2001 From: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Date: Wed, 23 Oct 2024 13:04:38 -0700 Subject: [PATCH] [docs] Copyedit the Charts Getting Started sequence (#14962) Signed-off-by: Sycamore <71297412+samuelsycamore@users.noreply.github.com> Co-authored-by: Alexandre Fauquette <45398769+alexfauquette@users.noreply.github.com> Co-authored-by: Victor Zanivan Monteiro --- .../charts/getting-started/getting-started.md | 98 +++++++------------ docs/data/charts/overview/overview.md | 25 +++-- docs/data/introduction/support/support.md | 2 +- .../modules/components/ChartFeaturesGrid.js | 34 ++++++- 4 files changed, 79 insertions(+), 80 deletions(-) diff --git a/docs/data/charts/getting-started/getting-started.md b/docs/data/charts/getting-started/getting-started.md index 6c6057abfc00..83dbff7001c7 100644 --- a/docs/data/charts/getting-started/getting-started.md +++ b/docs/data/charts/getting-started/getting-started.md @@ -4,20 +4,20 @@ githubLabel: 'component: charts' packageName: '@mui/x-charts' --- -# Charts - Getting Started +# Charts - Getting started -

Get started with the MUI X Charts components. Install the package, configure your application, and start using the components.

+

Install the MUI X Charts package to start building React data visualization components.

## Installation -Using your favorite package manager, install `@mui/x-charts-pro` for the commercial version, or `@mui/x-charts` for the free community version. +Run one of the following commands to install the free Community version or the paid Pro version of the MUI X Charts: {{"component": "modules/components/ChartsInstallationInstructions.js"}} -The Charts package has a peer dependency on `@mui/material`. -If you are not already using it in your project, you can install it with: +The Charts packages have a peer dependency on `@mui/material`. +If you're not already using it, install it with the following command: @@ -37,7 +37,7 @@ yarn add @mui/material @emotion/react @emotion/styled -Please note that [react](https://www.npmjs.com/package/react) and [react-dom](https://www.npmjs.com/package/react-dom) are peer dependencies too: +[`react`](https://www.npmjs.com/package/react) and [`react-dom`](https://www.npmjs.com/package/react-dom) are also peer dependencies: ```json "peerDependencies": { @@ -46,85 +46,66 @@ Please note that [react](https://www.npmjs.com/package/react) and [react-dom](ht }, ``` -### Style engine - -Material UI is using [Emotion](https://emotion.sh/docs/introduction) as a styling engine by default. If you want to use [`styled-components`](https://styled-components.com/) instead, run: - - -```bash npm -npm install @mui/styled-engine-sc styled-components -``` - -```bash pnpm -pnpm add @mui/styled-engine-sc styled-components -``` - -```bash yarn -yarn add @mui/styled-engine-sc styled-components -``` - - - -Take a look at the [Styled engine guide](/material-ui/integrations/styled-components/) for more information about how to configure `styled-components` as the style engine. - ### Usage with D3 To help folks using CommonJS, the `@mui/x-charts` package uses a vendored package named `@mui/x-charts-vendor` to access D3 libraries. +You can import D3 functions from `@mui/x-charts-vendor/d3-color`. -If you need some D3 functions, you can import them with `@mui/x-charts-vendor/d3-color`. +## Rendering Charts -## Displaying charts +MUI X Charts can be rendered as _self-contained_ or _composable_ components. +[Self-contained components](#self-contained-charts) are simpler to get started with and are recommended for most common use cases; more complex visualization (such as combining Bar and Line Charts on a single plot) requires [custom composition](#composable-charts). -A Chart can be rendered in one of two ways: as a single component, or by composing subcomponents. +### Self-contained Charts -### Single charts +Self-contained Chart components are imported and rendered as a single React component (such as `` or ``) which contains all of the necessary subcomponents. -For common use cases, the single component is the recommended way. -Those components' names end with "Chart", as opposed to "Plot", and only require the series prop describing the data to render. +These components require a `series` prop describing the data to render, as well as a numerical value (rendered in pixels) for the `height` prop. +The `width` prop is optional; if no value is provided, the Charts expand to fill the available space. {{"demo": "SimpleCharts.js"}} -### Composed charts +### Composable Charts -To combine different Charts, like Lines with Bars, you can use composition with the `ChartContainer` wrapper. +More complex use cases require composition of the necessary subcomponents inside of a Chart Container wrapper. +Subcomponents include: -Inside this wrapper, render either axis components, such as `XAxis` and `YAxis`, or any plot component like `BarPlot`, `LinePlot`, `AreaPlot`, and `ScatterPlot`. +- Axis components – to define the X and Y axes +- Plot components – to create Bars, Lines, or any other Chart type +- Auxillary components - to add Tooltips, Highlights, and more +- Utilities - such as classes and types -Visit the [Composition page](/x/react-charts/composition/) for more details. +See the [Charts composition documentation](/x/react-charts/composition/) for complete details. -{{"demo": "Combining.js"}} +The demo below shows how to use composition to create a custom Chart that combines a Bar and a Line Chart on a single plot: -### Positions +{{"demo": "Combining.js"}} -Charts are composed of two main areas. -The SVG defined by its `width` and `height` delimits the available space. +## Chart layouts -Within this SVG, a dedicated "drawing area" (aka "plot area") serves as the canvas for data representation. -Here, elements like lines, bars, and areas visually depict the information. -It's controlled by the `margin = {top, bottom, left, right}` object defining the margin between the SVG and the drawing area. +The layout of a Chart is defined by two main spaces: the plot area, and the outer margins. -The space left by margins can display axes, titles, a legend, or any other additional information. +The `width` and `height` props define the dimensions of the SVG which is the root of the chart. +Within this SVG, the plot area (or drawing area) serves as the canvas for data visualization, where the lines, bars or other visual elements are rendered. +The size of the plot area is determined by the `margin = {top, bottom, left, right}` object which defines its outer margins inside the SVG. +The outer margin space is where information like axes, titles, and legends are displayed. -For more information about the position configuration, visit the [styling page](/x/react-charts/styling/#styling). +See the [Styling documentation](/x/react-charts/styling/#placement) for complete details. ## Axis management -MUI X Charts have a flexible approach to axis management, supporting multiple-axis charts with any combination of scales and ranges. - -Visit the [Axis page](/x/react-charts/axis/) for more details. - -## Styling +MUI X Charts take a flexible approach to axis management, with support for multiple axes and any combination of scales and ranges. -MUI X Charts follows the Material UI styling and features all of the customization tools you'd find there, making tweaking charts as straightforward as designing buttons. - -Visit the [Styling page](/x/react-charts/styling/) for more details. +See the [Axis documentation](/x/react-charts/axis/) for complete details. ## TypeScript -In order to benefit from the [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users need to import the following types. -Internally, it uses module augmentation to extend the default theme structure. +To benefit from [CSS overrides](/material-ui/customization/theme-components/#theme-style-overrides) and [default prop customization](/material-ui/customization/theme-components/#theme-default-props) with the theme, TypeScript users must import the following types. +These types use module augmentation to extend the default theme structure. ```tsx +// only one import is necessary, +// from the version you're currently using. import type {} from '@mui/x-charts/themeAugmentation'; import type {} from '@mui/x-charts-pro/themeAugmentation'; @@ -140,8 +121,3 @@ const theme = createTheme({ }, }); ``` - -:::info -You don't have to import the theme augmentation from both `@mui/x-charts` and `@mui/x-charts-pro` when using `@mui/x-charts-pro`. -Importing it from `@mui/x-charts-pro` is enough. -::: diff --git a/docs/data/charts/overview/overview.md b/docs/data/charts/overview/overview.md index ef86f4a0793f..92f1d289714d 100644 --- a/docs/data/charts/overview/overview.md +++ b/docs/data/charts/overview/overview.md @@ -7,34 +7,33 @@ packageName: '@mui/x-charts' # MUI X Charts -

A fast and extendable library of react chart components for data visualization.

+

A collection of React chart components for data visualization.

{{"component": "@mui/docs/ComponentLinkHeader", "design": false}} ## Overview -The `@mui/x-charts` is an MIT library for rendering charts relying on [D3.js](https://d3js.org/) for data manipulation and SVG for rendering. -And, like other MUI X components, charts are production-ready components that integrate smoothly into your app. +MUI X Charts is a library of production-ready components for rendering charts with React. +It uses [D3.js](https://d3js.org/) for data manipulation and SVGs for rendering. -With a high level of customization, MUI X Charts provides three levels of customization layers: **single components** with great defaults, extensive **configuration props**, and **subcomponents** for flexible composition. -Additionally, you can also use all the [MUI System](https://mui.com/system/getting-started/) tools, such as the theme override or the `sx` prop. +The components provide a high level of customization, with beautiful defaults as well as extensive configuration props and flexible composition options. +They also have access to all [MUI System](https://mui.com/system/getting-started/) tools such as theme overrides and the `sx` prop. {{"demo": "ChartsOverviewDemo.js", "defaultCodeOpen": true}} -## Using the documentation +## All MUI X Charts -The MUI X Charts documentation has a slightly different structure than other MUI X components. -Instead of having a long page for each, the pages are divided in two: +{{"component": "modules/components/ChartComponentsGrid.js"}} -1. General description of the built-in features the component provides. -2. A set of examples demonstrating the component with customizations. +## Using this documentation -## All MUI X Charts components +Each Chart type has two accompanying documents: -{{"component": "modules/components/ChartComponentsGrid.js"}} +1. **Overview** – a general description of built-in features +2. **Demo** – a collection of custom examples ## Supported features -The features that are shared across multiple Charts components, such as axes and legends, are also documented on separate pages. +Features shared across Chart components such as axes and legends are described in standalone documents: {{"component": "modules/components/ChartFeaturesGrid.js"}} diff --git a/docs/data/introduction/support/support.md b/docs/data/introduction/support/support.md index 3f65903d7dfb..ebba1a99214b 100644 --- a/docs/data/introduction/support/support.md +++ b/docs/data/introduction/support/support.md @@ -42,7 +42,7 @@ You can browse the documentation, find an example close to your use case, and th - [Data Grid](/x/react-data-grid/#mit-license-free-forever) - [Date Pickers](/x/react-date-pickers/getting-started/#render-your-first-component) -- [Charts](/x/react-charts/getting-started/#single-charts) +- [Charts](/x/react-charts/getting-started/#self-contained-charts) - [Tree View](/x/react-tree-view/#simple-tree-view) #### Use starter templates diff --git a/docs/src/modules/components/ChartFeaturesGrid.js b/docs/src/modules/components/ChartFeaturesGrid.js index 36af272ba23c..7da1be867826 100644 --- a/docs/src/modules/components/ChartFeaturesGrid.js +++ b/docs/src/modules/components/ChartFeaturesGrid.js @@ -1,12 +1,16 @@ import * as React from 'react'; import Grid from '@mui/material/Grid'; import { InfoCard } from '@mui/docs/InfoCard'; -import LineAxisRoundedIcon from '@mui/icons-material/LineAxisRounded'; +import ChatBubbleRoundedIcon from '@mui/icons-material/ChatBubble'; import DashboardCustomizeRoundedIcon from '@mui/icons-material/DashboardCustomizeRounded'; +import ExtensionRoundedIcon from '@mui/icons-material/Extension'; +import HighlightRoundedIcon from '@mui/icons-material/Highlight'; +import LabelImportantRoundedIcon from '@mui/icons-material/LabelImportant'; import LegendToggleRoundedIcon from '@mui/icons-material/LegendToggleRounded'; +import LineAxisRoundedIcon from '@mui/icons-material/LineAxisRounded'; import StackedBarChartRoundedIcon from '@mui/icons-material/StackedBarChartRounded'; import StyleRoundedIcon from '@mui/icons-material/StyleRounded'; -import TipsAndUpdatesRoundedIcon from '@mui/icons-material/TipsAndUpdatesRounded'; +import ZoomInRoundedIcon from '@mui/icons-material/ZoomIn'; const content = [ { @@ -19,6 +23,16 @@ const content = [ link: '/x/react-charts/components/', icon: , }, + { + title: 'Composition', + link: '/x/react-charts/composition/', + icon: , + }, + { + title: 'Label', + link: '/x/react-charts/label/', + icon: , + }, { title: 'Legend', link: '/x/react-charts/legend/', @@ -35,9 +49,19 @@ const content = [ icon: , }, { - title: 'Tooltips and highlights', + title: 'Tooltips', link: '/x/react-charts/tooltip/', - icon: , + icon: , + }, + { + title: 'Highlighting', + link: '/x/react-charts/highlighting/', + icon: , + }, + { + title: 'Zoom and pan', + link: '/x/react-charts/zoom-and-pan/', + icon: , }, ]; @@ -45,7 +69,7 @@ export default function ChartFeaturesGrid() { return ( {content.map(({ icon, title, link }) => ( - + ))}