-
Notifications
You must be signed in to change notification settings - Fork 4.9k
DataViews: Update storybook to add more context #74819
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
55 changes: 55 additions & 0 deletions
55
packages/dataviews/src/dataviews/stories/best-practices.story.mdx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| import { Meta } from '@storybook/addon-docs/blocks'; | ||
|
|
||
| import * as DataViewsStories from './index.story'; | ||
|
|
||
| <Meta of={ DataViewsStories } name="Best practices" /> | ||
|
|
||
| # Data Views | ||
|
|
||
| Data Views allow users to display and interact with information through different layouts such as table or grid. It includes features like search, filtering, sorting, pagination, and customization options to adjust column order, items per page, and hide columns, enhancing data exploration and flexibility. | ||
|
|
||
| A typical flow might be: | ||
|
|
||
| - Use search and filters to narrow down a large collection. | ||
| - Adjust the layout and visible fields to match the task (compare, skim, or visually scan). | ||
| - Take inline actions on item metadata, or open an editing interface when more detail is needed. | ||
|
|
||
| ## Choosing a layout | ||
|
|
||
| ### When to use **List** | ||
|
|
||
| Use the **List** layout when: | ||
|
|
||
| - **Content needs the most compact layout**, whether because it's used in a constrained context, or if paired with a preview surface. | ||
| - Default information density allows for a reduced set of secondary metadata. | ||
| - The view needs to work well in **narrow spaces**. | ||
|
|
||
| List is a good fit for items like Pages that benefit from a live preview next to the list. | ||
|
|
||
| ### When to use **Grid** | ||
|
|
||
| Use the **Grid** layout when: | ||
|
|
||
| - **Visual previews across multiple items at once are important** for recognition (patterns, templates, media, products). | ||
| - You want a **card‑based experience**, with each item having its own tile (image + metadata). | ||
| - You expect more **browsing and scanning by look** than comparing raw values. | ||
|
|
||
| Grid works well when choosing “by look” is more important than comparing precise numbers or dates. | ||
|
|
||
| ### When to use **Table** | ||
|
|
||
| Use the **Table** layout when: | ||
|
|
||
| - Users need to **compare multiple attributes across items** at once. | ||
| - **Column headers and alignment** are critical for understanding the data. | ||
| - The task involves working with structured data. | ||
|
|
||
| Table is ideal for dense, structured information where sorting and scanning down aligned columns is the primary workflow, such as posts or comments where metadata is important for choosing the next action. | ||
|
|
||
| ## When to use something else | ||
|
|
||
| Data Views are designed for **browsing and managing collections**. In other situations, consider other components in the `@wordpress/dataviews` package: | ||
|
|
||
| - **Use `DataForm`** when the primary workflow primarily relates to **creating or editing a single item** at a level that doesn't require a full editor. | ||
| - **Use `DataViewsPicker`** when the goal is **selecting one or more items** and returning that selection to another part of the UI. This is a better fit for dialogs and sidebars where the outcome is a selection, not ongoing management of a collection, e.g. inserting from a media library. | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.
@storybook/addon-docsis not declared as a dev dependency for dataviews. It's being sourced from here by npmgutenberg/packages/components/package.json
Line 106 in 10ea412
Such missing dependencies become a problem moving forward. Imagine if components removes that dependency, then dataviews will break because of this.
It's these types of issues we are trying to fix in #74689
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.
What would be a good fix for me to follow up on?
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.
Adding this to
devDependenciesinpackages/dataviews/package.jsonand runningnpm installThere 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.
Thanks. I have a full day today, but I'll put in a reminder and get to this as soon as I have a moment, unless someone else beats me to it in which case I'd be happy to approve.
Uh oh!
There was an error while loading. Please reload this page.
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.
Sure. I have created #74935 to fix it.