https://github.com/patternfly/react-data-view
https://github.com/patternfly/react-data-view
hacktoberfest
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/patternfly/react-data-view
- Owner: patternfly
- License: mit
- Created: 2024-04-11T15:19:09.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-07T19:32:20.000Z (8 months ago)
- Last Synced: 2025-05-07T20:28:22.619Z (8 months ago)
- Topics: hacktoberfest
- Language: TypeScript
- Homepage:
- Size: 15.7 MB
- Stars: 1
- Watchers: 28
- Forks: 7
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# PatternFly Data view
This repo contains React Data view implementation.
### Branches
`main` - PatternFly 6 implementation
`v5` - PatternFly 5 implementation
> NOTE: In the case of data view, new features are currently primarily added to `v5` branch to be consumed by Red Hat projects, still using PatternFly 5. In the follow-up step, they should be mirrored to the `main` branch. For bug fixes, it is preferred to fix the bug for both versions (fix in one branch and cherry-pick to another). Pulling new changes from 5 to 6 and vice versa is not recommended using `rebase`. Rather, always cherry-pick specific commits to avoid getting lost in unnecessary conflicts.
---
## Contribution guide
### To add a data view sub-component:
1. create a folder in `src/` matching its name (for example `src/MyComponent`)
2. to the new folder add a new `.tsx` file named after the component (for example `src/MyComponent/MyComponent.tsx`)
3. to the same folder include an `index.ts` which will export the component as a default and then all necessary interfaces
4. if this file structure is not met, your component won't be exposed correctly
#### Example component:
```
import * as React from 'react';
import { Text } from '@patternfly/react-core';
import { createUseStyles } from 'react-jss';
// do not forget to export your component's interface
// always place the component's interface above the component itself in the code
export interface MyComponentProps {
text: String;
}
const useStyles = createUseStyles({
myText: {
fontFamily: 'monospace',
fontSize: 'var(--pf-v6-global--icon--FontSize--md)',
},
})
// do not use the named export of your component, just a default one
const MyComponent: React.FunctionComponent = () => {
const classes = useStyles();
return (
This is my new component
);
};
export default MyComponent;
```
#### Index file example:
```
export { default } from './MyComponent';
export * from './MyComponent';
```
#### Component directory structure example:
```
src
|- MyComponent
|- index.ts
|- MyComponent.tsx
```
### Component's API rules:
- prop names comply with PatternFly components naming standards (`variant`, `onClick`, `position`, etc.)
- the API is maximally simplified and all props are provided with a description
- it is built on top of existing PatternFly types without prop omitting
- it is well documented using the PatternFly documentation (`/packages/module/patternfly-docs/content/extensions/data-view/examples/MyComponent/MyComponent.md`) with examples of all possible use cases (`packages/module/patternfly-docs/content/extensions/data-view/examples/MyComponent/MyComponent[...]Example.tsx`)
#### Component API definition example:
```
// when possible, extend available PatternFly types
export interface MyComponentProps extends ButtonProps {
customLabel: Boolean
};
export const MyComponent: React.FunctionComponent = ({ customLabel, ...props }) => ( ... );
```
#### Markdown file example:
```
---
section: extensions
subsection: Data view
id: MyComponent
propComponents: ['MyComponent']
sourceLink: https://github.com/patternfly/react-data-view/blob/main/packages/module/patternfly-docs/content/extensions/data-view/examples/MyComponent/MyComponent.md
---
import MyComponent from "@patternfly/react-data-view/dist/dynamic/MyComponent";
## Component usage
MyComponent has been created to demo contributing to this repository.
### MyComponent component example label
```js file="./MyComponentExample.tsx"```
```
#### Component usage file example: (`MyComponentExample.tsx`)
```
import React from 'react';
const MyComponentExample: React.FunctionComponent = () => (
);
export default MyComponentExample;
```
### Sub-components:
When adding a component for which it is advantageous to divide it into several sub-components make sure:
- component and all its sub-components are located in separate files and directories straight under the `src/` folder
- sub-components are exported and documented separately from their parent
- parent component should provide a way to pass props to all its sub-components
The aim is to enable the user of our "complex" component to use either complete or take advantage of its sub-components and manage their composition independently.
### Testing:
When adding/making changes to a component, always make sure your code is tested:
- use React Testing Library for unit testing
- add unit tests to a `[ComponentName].test.tsx` file to your component's directory
- make sure all the core functionality is covered using Cypress component or E2E tests
- add component tests to `cypress/component/[ComponentName].cy.tsx` file and E2E tests to `cypress/e2e/[ComponentName].spec.cy.ts`
- add `ouiaId` to component props definition with a default value of the component name (for subcomponents, let's use `ComponentName-element-specification` naming convention e.g. `ouiaId="DataView-actions-button"`)
### Styling:
- for styling always use JSS
- new classNames should be named in camelCase starting with the name of a given component and following with more details clarifying its purpose/component's subsection to which the class is applied (`actionMenu`, `actionMenuDropdown`, `actionMenuDropdownToggle`, etc.)
- do not use `pf-v6-u-XXX` classes, use CSS variables in a custom class instead (styles for the utility classes are not bundled with the standard patternfly.css - it would require the consumer to import also addons.css)
---
## Building for production
- run `npm install`
- run `npm run build`
## Development
- run `npm install`
- run `npm run start` to build and start the development server
## Testing and Linting
- run `npm run test` to run the unit tests
- run `cypress:run:ci:cp` to run component tests
- run `cypress:run:ci:e2e` to run E2E tests
- run `npm run lint` to run the linter
## A11y testing
- run `npm run build:docs` followed by `npm run serve:docs`, then run `npm run test:a11y` in a new terminal window to run our accessibility tests. Once the accessibility tests have finished running you can run `npm run serve:a11y` to locally view the generated report