IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Edit of 4 files in contribute/style-guides (part 9 of doc quality improvement project) (#90705)

Browse Source 
* Docs: Edit of 4 files in contribute/style-guides

* Respond to review question

* Fix unordered list

* Update contribute/style-guides/e2e-core.md

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* Update contribute/style-guides/e2e-core.md

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* Update contribute/style-guides/e2e-core.md

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>

* Fix title

* Prettier fixes

---------

Co-authored-by: Christopher Moyer <35463610+chri2547@users.noreply.github.com>
This commit is contained in:
Joseph Perez 2024-07-25 11:14:19 -07:00 committed by GitHub
parent 3c405e8b1f
commit 3df7a854e6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 114 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
contribute/style-guides/accessibility.md
View File

@ -1,24 +1,20 @@
# Accessibility at Grafana
# Develop for accessibility at Grafana
At Grafana we pay special attention to accessibility and that's why it's important that all components are written with it in
mind.
The goal of this document is to list best practices and recommendations when it comes to writing accessible components.
At Grafana we pay special attention to accessibility (a11y) and that's why it's important that all components are written with it in mind. This document contains some best practices for writing accessible components.
### grafana/ui components
Some grafana/ui components have specific mechanisms built-in that make it easier to write accessible components.
Some `grafana/ui` components have specific built-in mechanisms that make it easier to write accessible components.
#### Form elements
One of the important accessibility considerations when working with form elements is to make sure form controls are
properly labelled. For that a `label` element has to be associated with the respective form control. One way to
do that is to provide `for` attribute to the label that matches the `id` attribute of the form control.
One of the important accessibility considerations when working with form elements is to make sure form controls are properly labelled.
For example, a `label` element should be associated with the respective form control.
One way to do that is to provide a `for` attribute to the label that matches the `id` attribute of the form control.
The form components from grafana/ui provide an easier way to achieve that. The form elements, used inside `Field`
components, will get the `label` properly associated with them given that the element has `id` (in case of `Select` the prop is `inputId`) specified.
The form components from `grafana/ui` provide an easier way to achieve that. The form elements, used inside `Field` components, get the `label` properly associated with them. This is appropriate because the element has a specified `id` (in case of `Select`, the prop is `inputId`).
As an example, this code
For example:
```tsx
<Field label="Name">
@ -26,7 +22,7 @@ As an example, this code
</Field>
```
will be rendered as (simplified)
In the previous example, the code is rendered as:
```html
<div>
@ -35,18 +31,19 @@ will be rendered as (simplified)
</div>
```
As long as the form element has a unique `id` attribute specified, it will be automatically accessible when rendered.
As long as the form element has a unique `id` attribute specified, it's automatically accessible when rendered.
### Writing tests with accessibility in mind
### Write tests with accessibility in mind
We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) (RTL) for writing unit tests.
We use the [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) (RTL) for writing unit tests.
The library is built with accessibility in mind and makes it easier to ensure the written code is accessible to all users.
When querying DOM elements with RTL prefer using `*ByRole` queries as they resemble closely how the users interact
with the page - both using mouse/visual display and assistive technologies.
As a rule of thumb, if code is written with the accessibility concerns in
mind, `*ByRole` queries will be sufficient in most of the cases. There are certainly exceptions here, as not all the elements have defined [ARIA role](https://www.w3.org/TR/html-aria/#docconformance).
As an example, for this code
When querying DOM elements with RTL, you should prefer using `*ByRole` queries as they resemble closely how the users interact with the page. These queries use mouse and visual displays and assistive technologies.
As a rule of thumb, when code is written with accessibility concerns in
mind, `*ByRole` queries are sufficient in most cases. However, there are exceptions because not all the elements have defined [ARIA roles](https://www.w3.org/TR/html-aria/#docconformance).
For example:
```tsx
<Field label="Username">
@ -54,7 +51,7 @@ As an example, for this code
</Field>
```
the test could case be as follows
In the previous example, the test case is the following code:
```tsx
it('has username set', () => {
@ -62,16 +59,15 @@ it('has username set', () => {
});
```
Input with type `text` (default type value) has a role of `textbox` and the `name` option is not the name attribute
given to the input elements but their [accessible name](https://www.tpgi.com/what-is-an-accessible-name/), which in this case is the text content of the associated with input label.
Input with type `text` (that is, the default type value) has a role of `textbox`. Also, the `name` option isn't the name attribute given to the input elements, but their [accessible name](https://www.tpgi.com/what-is-an-accessible-name/). The accessible name in this case is the text content associated with the input label.
### Pull requests that introduce accessibility(a11y) errors:
### Pull requests that introduce accessibility errors:
We use [pa11y-ci](https://github.com/pa11y/pa11y-ci) to collect accessibility errors on [some URLs in the project](https://github.com/grafana/grafana/issues/36555), threshold errors are specified per URL.
We use [pa11y-ci](https://github.com/pa11y/pa11y-ci) to collect accessibility errors on [some URLs in the project](https://github.com/grafana/grafana/issues/36555). The thresholds of accessibility errors are specified per URL.
If the contribution introduces new a11y errors, our continuous integration will fail, preventing you to merge to the main branch. In those cases there are two alternatives for moving forward:
If the contribution introduces new a11y errors, our continuous integration will fail, preventing you from merging to the main branch. In those cases there are two alternatives for moving forward:
- Check the error log on the pipeline step `test-a11y-frontend-pr`, identify what was the error, and fix it.
- Locally run the command `yarn test:accessibility-report` that generates an HTML accessibility report, then go to the URL that contains your change, identify the error, and fix it. Keep in mind, a local e2e Grafana instance is going to be running on `http://localhost:3001`.
- Check the error log on the pipeline step `test-a11y-frontend-pr`, identify the nature of the error, and then fix it.
- Locally run the command `yarn test:accessibility-report` that generates an HTML accessibility report, and then go to the URL that contains your change. On this URL, identify the error, and then fix it. Keep in mind that a local end-to-end Grafana instance is going to be running on `http://localhost:3001`.
You can also prevent introducing a11y errors by installing an a11y plugin in your browser, for example, axe DevTools, Accessibility Insights for Web among others.
You can also avoid introducing accessibility errors by installing an a11y plugin in your browser. For example, you could use axe DevTools or Accessibility Insights for Web, among others.

70
contribute/style-guides/code-comments.md
View File

@ -1,45 +1,36 @@
# Guidelines for code comments in grafana-\* packages
# Guidelines for code comments in Grafana packages
This document aims to give you some recommendation on how to add code comments to the exported code in the grafana packages.
## Table of Contents
1. [Add package description](#add-package-description)
1. [Set stability of an API](#set-stability-of-an-api)
1. [Deprecate an API](#deprecate-an-api)
1. [Specify parameters](#specify-parameters)
1. [Set return values](#set-return-values)
---
This guide provides recommendations for adding code comments in `grafana-\*` packages.
## Add package description
Each package has an overview explaining the overall responsibility and usage of the package.
You can document this description with [`@packageDocumentation`](https://api-extractor.com/pages/tsdoc/tag_packagedocumentation/) tag.
Use the [`@packageDocumentation`](https://api-extractor.com/pages/tsdoc/tag_packagedocumentation/) tag to document the package.
Add this tag to the `<packageRoot>/src/index.ts` entry file to have one place for the package description.
Add the `@packageDocumentation` tag to the `<packageRoot>/src/index.ts` entry file to have one place for the package description.
## Set stability of an API
All `exported` apis from the package should have a release tag to indicate its stability.
Add a release tag to all exported APIs from the package to indicate its stability.
- [`@alpha`](https://api-extractor.com/pages/tsdoc/tag_alpha/) - early draft of api and will probably change.
- [`@beta`](https://api-extractor.com/pages/tsdoc/tag_beta/) - close to being stable but might change.
- [`@public`](https://api-extractor.com/pages/tsdoc/tag_public/) - ready for usage in production.
- [`@internal`](https://api-extractor.com/pages/tsdoc/tag_internal/) - for internal use only.
- [`@alpha`](https://api-extractor.com/pages/tsdoc/tag_alpha/) - denotes an early draft of API that will probably change.
- [`@beta`](https://api-extractor.com/pages/tsdoc/tag_beta/) - denotes that the API is close to being stable but might change.
- [`@public`](https://api-extractor.com/pages/tsdoc/tag_public/) - denotes that the API is ready for usage in production.
- [`@internal`](https://api-extractor.com/pages/tsdoc/tag_internal/) - denotes that the API is for internal use only.
### Main stability of APIs
### Indicate main stability of APIs
Add a tag to mark the stability of the whole exported `class/interface/function/type` etc.
To indicate the main stability of APIs:
Please place the `release tag` at the bottom of the comment to make it consistent among files and easier to read.
- Add a tag to mark the stability of the whole exported `class/interface/function/type`, and other interfaces.
- Place the release tag at the bottom of the comment to make it consistent among files and easier to read.
**Do:**
````typescript
/**
* Will help to create DataFrame objects and handle
* Helps to create DataFrame objects and handle
* the heavy lifting of creating a complex object.
*
* @example
@ -54,11 +45,11 @@ export class DataFrameFactory {
}
````
**Don't**
**Don't:**
````typescript
/**
* Will help to create DataFrame objects and handle
* Helps to create DataFrame objects and handle
* the heavy lifting of creating a complex object.
*
* @public
@ -72,17 +63,18 @@ export class DataFrameFactory {
}
````
### Partial stability of APIs
### Indicate partial stability of APIs
Add the main stability of the API at the top according to [Main stability of API](#main-stability-of-api).
To indicate the partial stability of APIs:
Then override the non-stable parts of the API with the proper [release tag](#release-tags). This should also be place at the bottom of the comment block.
1. Add the main stability of the API at the top according to [Main stability of API](#indicate-main-stability-of-apis).
1. Override the non-stable parts of the API with the proper release tag. This tag should also be placed at the bottom of the comment block.
**Do:**
````typescript
/**
* Will help to create DataFrame objects and handle
* Helps to create DataFrame objects and handle
* the heavy lifting of creating a complex object.
*
* @example
@ -102,11 +94,11 @@ export class DataFrameFactory {
}
````
**Don't**
**Don't:**
````typescript
/**
* Will help to create DataFrame objects and handle
* Helps to create DataFrame objects and handle
* the heavy lifting of creating a complex object.
*
* @example
@ -131,7 +123,7 @@ export class DataFrameFactory {
If you want to mark an API as deprecated to signal that this API will be removed in the future, then add the [`@deprecated`](https://api-extractor.com/pages/tsdoc/tag_deprecated/) tag.
If applicable add a reason why the API is deprecated directly after the `@deprecated tag`.
If applicable, add a reason why the API is deprecated directly after the `@deprecated tag`.
## Specify parameters
@ -143,7 +135,7 @@ This attribute can be skipped if the type provided by `typescript` and the funct
```typescript
/**
* Will help to create a resource resolver depending
* Helps to create a resource resolver depending
* on the current execution context.
*
* @param context - The current execution context.
@ -162,7 +154,7 @@ export const factory = (context: Context): IResolver => {
```typescript
/**
* Will compare two numbers to see if they are equal to each others.
* Compares two numbers to see if they are equal to each other.
*
* @param x - The first number
* @param y - The second number
@ -175,15 +167,15 @@ export const isEqual = (x: number, y: number): boolean => {
## Set return values
If you want to specify the return value from a function you can use the [`@returns`](https://api-extractor.com/pages/tsdoc/tag_returns/) tag.
To specify the return value from a function, you can use the [`@returns`](https://api-extractor.com/pages/tsdoc/tag_returns/) tag.
This attribute can be skipped if the type provided by `typescript` and the function comment or the function name is enough to explain what the function returns.
You can skip this attribute if the type provided by `typescript` and the function comment or the function name is enough to explain what the function returns.
**Do:**
```typescript
/**
* Will help to create a resource resolver depending
* Helps to create a resource resolver depending
* on the current execution context.
*
* @param context - The current execution context.
@ -198,11 +190,11 @@ export const factory = (context: Context): IResolver => {
};
```
**Don't**
**Don't:**
```typescript
/**
* Will compare two numbers to see if they are equal to each others.
* Compares two numbers to see if they are equal to each other.
*
* @returns true if values are equal
* @public

20
contribute/style-guides/e2e-core.md
View File

@ -1,12 +1,12 @@
# End-to-End Tests for core Grafana
# End-to-end tests for core Grafana
This document is specific to the [Grafana repository](https://github.com/grafana/grafana). Be sure that you've read the [generalized E2E document](e2e.md).
This guide explains how to conduct end-to-end tests for the [Grafana repository](https://github.com/grafana/grafana). Ensure that you've read the [generalized E2E document](e2e.md).
## Commands
- `yarn e2e` Creates an isolated `grafana-server` home under _\<repo-root>/e2e/tmp_ with provisioned data sources and dashboards. This copies locally build binary and frontend assets from your repo root so you need to have a built backend and frontend for this to run locally. The server starts on port 3001 so it does not conflict with your normal dev server.
- `yarn e2e:debug` Same as above but runs the tests in chrome and does not shutdown after completion.
- `yarn e2e:dev` Same as above but does not run any tests on startup. It lets you pick a test first.
- `yarn e2e`: Creates an isolated `grafana-server` home under `\<repo-root>/e2e/tmp` with provisioned data sources and dashboards. This makes a local copy of the build binary and frontend assets from your repository root so you need to have a built backend and frontend. The server starts on port `3001` so it does not conflict with your normal dev server.
- `yarn e2e:debug`: Same as previous but runs the tests in Chrome and doesn't shut down after completion.
- `yarn e2e:dev`: Same as previous but does not run any tests on startup. It lets you pick a test first.
If you already have a Grafana instance running, you can provide a specific URL by setting the `BASE_URL` environment variable:
@ -14,12 +14,12 @@ If you already have a Grafana instance running, you can provide a specific URL b
BASE_URL=http://172.0.10.2:3333 yarn e2e
```
The above commands use some utils scripts under [_\<repo-root>/e2e_](../../e2e) that can also be used for more control.
The previous commands use some `utils` scripts under [_\<repo-root>/e2e_](../../e2e) that you can also use for more control.
- `./scripts/grafana-server/start-server` This creates a fresh new grafana server working dir, setup's config and starts the server. It will also kill any previously started server that is still running using pid file at _\<repo-root>/scripts/grafana-server/tmp/pid_.
- `./scripts/grafana-server/wait-for-grafana` waits for `$HOST` and `$PORT` to be available. Per default localhost and 3001.
- `./e2e/run-suite <debug|dev|noarg>` Starts cypress in different modes.
- `./scripts/grafana-server/start-server`: This creates a new Grafana server working directory, sets up configuration. and starts the server. It also kills any previously started server that is still running using the `pid` file at `\<repo-root>/scripts/grafana-server/tmp/pid`.
- `./scripts/grafana-server/wait-for-grafana`: waits for `$HOST` and `$PORT` to be available. Per default `localhost` and `3001`.
- `./e2e/run-suite <debug|dev|noarg>`: Starts Cypress in different modes.
## Test suites
All the integration tests are located at _\<repo-root>/e2e/suite\<x>/specs_.
You can find integration tests at `\<repo-root>/e2e/suite\<x>/specs`.

82
contribute/style-guides/themes.md
View File

@ -1,23 +1,25 @@
# Theming Grafana
# Work with Grafana themes
## Overview
**Themes are implemented in Typescript.** That's because our goal is to share variables between Grafana TypeScript and [Sass](https://sass-lang.com/) code. Theme definitions are located in the following files:
Themes in Grafana are implemented in TypeScript. We chose the TypeScript language in part because it shares variables between Grafana TypeScript and [Sass](https://sass-lang.com/) code.
Theme definitions are located in the following files:
- [packages/grafana-data/src/themes/createTheme.ts](../../packages/grafana-data/src/themes/createTheme.ts)
- [packages/grafana-data/src/themes/createColors.ts](../../packages/grafana-data/src/themes/createColors.ts)
## Usage
This section provides usage guidelines.
This section provides usage guidelines for themes.
### Using themes in React components
### Use themes in React components
Here's how to use Grafana themes in React components.
The following section describes how to use Grafana themes in React components.
#### useStyles2 hook
#### The useStyles2 hook
`useStyles2` memoizes the function and provides access to the theme.
The `useStyles2` hook memoizes the function and provides access to the theme.
```tsx
import { FC } from 'react';
@ -38,6 +40,8 @@ const getStyles = (theme: GrafanaTheme2) =>
#### Get the theme object
Use code similar to the following to give your component access to the theme variables:
```tsx
import { FC } from 'react';
import { useTheme2 } from '@grafana/ui';
@ -49,12 +53,22 @@ const Foo: FC<FooProps> = () => {
};
```
## Picking the right variable
## Select a variable
This section explains how to select the correct variables in your theme.
### The rich color object and the state colors
The theme.colors object has 6 rich color objects for `primary`, `secondary`, `info`, `success`, `warning` and `error`. These all
have the same sub colors that have different use cases.
The `theme.colors` object has six rich color objects:
- `primary`
- `secondary`
- `info`
- `success`
- `warning`
- `error`
All these objects use the same secondary colors which are associated with different use cases.
| Property | When to use |
| ------------ | ---------------------------------------------------------- |
@ -66,9 +80,9 @@ have the same sub colors that have different use cases.
Example use cases:
- Want a `red` background? Use `theme.colors.error.main`
- Want `green` text? Use `theme.colors.success.text`
- Want text to be visible when placed inside a background that uses `theme.colors.error.main` then use `theme.colors.error.contrastText`.
- Want a red background? Use `theme.colors.error.main`.
- Want green text? Use `theme.colors.success.text`.
- Want text to be visible when placed inside a background that uses `theme.colors.error.main`? Use `theme.colors.error.contrastText`.
### Text colors
@ -76,17 +90,17 @@ Example use cases:
| ----------------------------- | ------------------------------------------------------------------------------ |
| theme.colors.text.primary | The default text color |
| theme.colors.text.secondary | Text color for things that should be a bit less prominent |
| theme.colors.text.disabled | Text color for disabled / faint things |
| theme.colors.text.disabled | Text color for disabled or faint things |
| theme.colors.text.link | Text link color |
| theme.colors.text.maxContrast | Maximum contrast (absolute white in dark theme, absolute black in white theme) |
### Background colors
| Property | When to use |
| --------------------------------- | ------------------------------------------------------------------------------------------------- |
| theme.colors.background.canvas | Think dashboard background. A background surface for panels and panes that use primary background |
| theme.colors.background.primary | The default content background for content panes and panels |
| theme.colors.background.secondary | For cards and other surfaces that need to stand out when placed on top of the primary background |
| Property | When to use |
| --------------------------------- | ------------------------------------------------------------------------------------------------ |
| theme.colors.background.canvas | Dashboard background. A background surface for panels and panes that use primary background |
| theme.colors.background.primary | The default content background for content panes and panels |
| theme.colors.background.secondary | For cards and other surfaces that need to stand out when placed on top of the primary background |
### Borders
@ -121,9 +135,11 @@ Example use cases:
### Typography
For font family, font sizes and line heights use the variables under `theme.typography`.
To customize font family, font sizes, and line heights, use the variables under `theme.typography`.
#### Using `ThemeContext` directly
#### Set the context directly
Use `ThemeContext` like this:
```tsx
import { ThemeContext } from '@grafana/data';
@ -131,9 +147,9 @@ import { ThemeContext } from '@grafana/data';
<ThemeContext.Consumer>{(theme) => <Foo theme={theme} />}</ThemeContext.Consumer>;
```
#### Using `withTheme` higher-order component (HOC)
#### Use `withTheme` higher-order component
With this method your component will be automatically wrapped in `ThemeContext.Consumer` and provided with current theme via `theme` prop. Components used with `withTheme` must implement the `Themeable` interface.
With this method your component will be automatically wrapped in `ThemeContext.Consumer` and provided with current theme via the `theme` prop. Components used with `withTheme` must implement the `Themeable` interface.
```ts
import { ThemeContext, Themeable } from '@grafana/ui';
@ -145,10 +161,9 @@ const Foo: React.FunctionComponent<FooProps> = () => ...
export default withTheme2(Foo);
```
### Using theme in tests
### Use a theme in tests
If you need to pass a theme object to a function under test just import `createTheme` and call it without
any arguments.
If you need to pass a theme object to a function that you are testing, then import `createTheme` and call it without any arguments. For example:
```tsx
import { createTheme } from '@grafana/data';
@ -161,17 +176,14 @@ describe('MyComponent', () => {
});
```
## FAQ
### Modify Sass variables
This section provides insight into frequently-asked questions.
If you need to modify the Sass variable files, we recommend that you migrate the styles to [Emotion](https://emotion.sh/docs/introduction).
### How can I modify Sass variable files?
For the following variables to apply, you need to run this `yarn dev` task:
**If possible, migrate styles to Emotion**
- `[_variables|_variables.dark|_variables.light].generated.scss`: These files must be referenced in the main Sass files for Sass variables to be available.
> For the following to apply you need to run `yarn dev` task.
If you need to modify the Sass variable files, be sure to update the files that end with `.tmpl.ts` and not the `.generated.scss` files.
`[_variables|_variables.dark|_variables.light].generated.scss` files are the ones that are referenced in the main Sass files for Sass variables to be available. **These files are automatically generated and should never be modified by hand!**
If you need to modify the sass variable files be sure to update the files that end with `.tmpl.ts` and
not the `.generated.scss` files.
> **Important:** These variable files are automatically generated and should never be modified by hand.