Skip to content

Commit

Permalink
chore: update objects list template to use filter pattern (#4059)
Browse files Browse the repository at this point in the history
* chore: update objects list template to use filter pattern

* chore: make popovers open

* chore: docs

* chore: add plus icon

* chore: disable a11y
  • Loading branch information
nkrantz authored Sep 12, 2024
1 parent 39a6b33 commit 337587d
Show file tree
Hide file tree
Showing 5 changed files with 155 additions and 118 deletions.
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
export const meta = {
title: 'Object details',
description:
'The Object details page template allows customers to view and take action on properties of a single object.',
'The object details page template allows customers to view and take action on properties of a single object.',
slug: '/page-templates/object-details/',
};

Expand Down Expand Up @@ -46,17 +46,17 @@ export const getStaticProps = async () => {
code={FullObjectDetailsExample}
/>

## About Object details
## About object details

Object details give customers a primarily read-only view of the properties of an object, such as a message log or sent email.

If the customer is primarily editing information, use the [Settings](/page-templates/settings) page instead.
If the customer is primarily editing information, use the [settings](/page-templates/settings) page template instead.

## Accessibility

A well-structured [document hierarchy](https://www.w3.org/WAI/tutorials/page-structure/) helps provide efficient in-page navigation for keyboard users, assistive technologies, and mobile web users.

Proper hierarchy allows users to skip directly to content that is most relevant to them. This is especially important on an Object details page where there may be many different types of information and customers are more likely to skim through.
Proper hierarchy allows users to skip directly to content that is most relevant to them. This is especially important on an object details page where there may be many different types of information and customers are more likely to skim through.

To structure a page:

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
export const meta = {
title: 'Objects list',
description:
'The Objects list page template shows a list of unique items for when a customer needs to perform an action on the items.',
'The objects list page template shows a list of unique items for when a customer needs to perform an action on the items.',
slug: '/page-templates/objects-list/',
};

Expand Down Expand Up @@ -45,18 +45,18 @@ export const getStaticProps = async () => {
code={FullObjectsListExample}
/>

## About Objects list
## About objects list

An Objects list shows a list of unique items or records (objects), such as logs or contacts. The page can include [search and filtering](/patterns/filter-group) to help customers find an item they’re looking for, and bulk actions like [export](/patterns/data-export) or [delete](/patterns/delete).
An objects list shows a list of unique items or records (objects), such as logs or contacts. The page can include [search and filtering](/patterns/filter) to help customers find an item they’re looking for, and bulk actions like [export](/patterns/data-export) or [delete](/patterns/delete).

Use an Objects list when a customer needs to:
Use an objects list when a customer needs to:

- View objects of a single type
- Find specific objects quickly so they can view more [object details](/page-templates/object-details), edit, or delete them
- Create a new object of this type
- Perform bulk actions on multiple objects

If the customer is primarily editing information, use the [Settings](/page-templates/settings) page instead.
If the customer is primarily editing information, use the [settings](/page-templates/settings) page instead.

## Ingredients

Expand All @@ -78,9 +78,9 @@ The full header should be responsive to the width of the browser window. Heading

### Body

The rest of the page follows the [Filter Group pattern](/patterns/filter-group) and uses a [Data Grid](/components/data-grid). If there’s already a primary action in the page header, make the filter button a secondary button. If there are no interactive cells, use a Table instead of a Data Grid.
The rest of the page follows the [filter pattern](/patterns/filter) and uses a [Data Grid](/components/data-grid). If there are no interactive cells, use a Table instead of a Data Grid.

If the customer needs to examine each object in more detail, link each object to its [Object details](/page-templates/object-details) page.
If the customer needs to examine each object in more detail, link each object to its [object details](/page-templates/object-details) page.

The body should be responsive to the width of the browser window.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
export const meta = {
title: 'Settings',
description: 'The Settings page template lets customers edit information and update simple settings.',
description: 'The settings page template lets customers edit information and update simple settings.',
slug: '/page-templates/settings/',
};

Expand Down Expand Up @@ -52,7 +52,7 @@ Settings pages let customers edit information and update simple settings.

If a customer is creating an object or the editing process is complex and requires additional guidance or focus, use the [create](/patterns/create) pattern and [wizard](/page-templates/wizard) template instead.

A Settings page can be a standalone page, or you can use a Settings overview page that links to multiple Settings pages.
A settings page can be a standalone page, or you can use a settings overview page that links to multiple settings pages.

## Ingredients

Expand All @@ -62,21 +62,21 @@ A Settings page can be a standalone page, or you can use a Settings overview pag

### Page header

At the top of the page, add a page heading using the format “[Settings type] settings.” For example, “Workplace settings” or “Source settings.” Optionally, use text under the heading to explain the primary settings on the page.
At the top of the page, add a page heading using the format “[settings type] settings.” For example, “Workplace settings” or “Source settings.” Optionally, use text under the heading to explain the primary settings on the page.

Heading and Paragraph should have a max width of `$size-70`.

### Body

Like [Object details](/page-templates/object-details), Settings should also allow a customer to easily scan for the information they’re looking to edit. Group related settings under Headings. Use sentence case for all Headings (“Billing details” not “Billing Details”).
Like [object details](/page-templates/object-details), settings should also allow a customer to easily scan for the information they’re looking to edit. Group related settings under Headings. Use sentence case for all Headings (“Billing details” not “Billing Details”).

If a group of settings needs additional explanation, use a Paragraph under a single Heading. If a single setting needs additional explanation, use Help Text with its form field.

Use customer research to inform how to order sections on the Settings page.
Use customer research to inform how to order sections on the settings page.

### Settings overview page

If there are too many settings to fit on a single page, split related settings into separate pages or Modals, and link to them from a Settings overview page. On a Settings overview page, use [Cards](/components/card) to group sections and surface the most relevant information with [Description Lists](components/description-list).
If there are too many settings to fit on a single page, split related settings into separate pages or Modals, and link to them from a Settings overview page. On a settings overview page, use [Cards](/components/card) to group sections and surface the most relevant information with [Description Lists](components/description-list).

Position the page content in the center with a max width of `$size-90`.

Expand Down
32 changes: 16 additions & 16 deletions packages/paste-website/src/pages/page-templates/wizard/index.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
export const meta = {
title: 'Wizard',
description: 'A Wizard focuses customers through a series of tasks to reach a goal.',
description: 'A wizard focuses customers through a series of tasks to reach a goal.',
slug: '/page-templates/wizard/',
};

Expand Down Expand Up @@ -47,9 +47,9 @@ export const getStaticProps = async () => {
code={DefaultWizardExample}
/>

## About Wizard
## About wizard

Use a Wizard when a customer’s goal is long or complex, and breaking it up into smaller page-by-page tasks allows the user to focus and not feel overwhelmed. A Wizard can be useful when the tasks to reach a goal are dependent on each other, and customers need to finish different tasks based on previous ones.
Use a wizard when a customer’s goal is long or complex, and breaking it up into smaller page-by-page tasks allows the user to focus and not feel overwhelmed. A wizard can be useful when the tasks to reach a goal are dependent on each other, and customers need to finish different tasks based on previous ones.

Start by splitting the goal across multiple tasks with each page containing just one main task, for example:
- One piece of information the customer needs to know
Expand Down Expand Up @@ -84,16 +84,16 @@ Before deciding on a page layout, make a few content and experience decisions fi
- **Task content:** Decide what content and components will help a customer finish each task.
- **Goal linearity and duration:** Decide whether a customer can achieve the entire goal in one session. Decide whether they need to leave Twilio to finish a task and whether they need to wait for Twilio to do something before finishing the flow.

There are 3 standard max-widths for the content of each Wizard page. Based on the content you need for each task, start with the smallest max-width and size up as needed:
There are 3 standard max-widths for the content of each wizard page. Based on the content you need for each task, start with the smallest max-width and size up as needed:
1. `size-70` (712px). If this is too small, use:
2. `size-100` (1024px). If this is too small, use:
3. Full-width, with a max-width of `size-70` for the Page Header.

Use the same max-width for each page of the Wizard if possible.
Use the same max-width for each page of the wizard if possible.

### Default template

In most scenarios, you’ll take customers through a Wizard without having to change the Sidebar or Topbar.
In most scenarios, you’ll take customers through a wizard without having to change the Sidebar or Topbar.

<StoryPreview
title="Wizard page template - default with content"
Expand All @@ -103,7 +103,7 @@ In most scenarios, you’ll take customers through a Wizard without having to ch

#### Page header

At the top of each page of the Wizard, add:
At the top of each page of the wizard, add:
- Wizard title as [Detail Text](/components/detail-text) (optional)
- Task [Heading](/components/heading)
- [Paragraph](/components/paragraph) text under the heading to explain the step (optional)
Expand All @@ -122,14 +122,14 @@ There may be cases where you need to show multiple tasks on the same page becaus

<Callout variant='neutral' marginY="space70">
<CalloutHeading as="h2">Looking for guidelines on progressive disclosures?</CalloutHeading>
<CalloutText>We don’t have guidelines yet for this part of Wizard. If you need it for your work, please consider partnering with us to contribute it.</CalloutText>
<CalloutText>We don’t have guidelines yet for this part of wizard. If you need it for your work, please consider partnering with us to contribute it.</CalloutText>
</Callout>

#### Actions footer

Use these actions in the footer, starting from the right side of the page:
- A primary, right-aligned next [Button](/components/button) to let a customer move to the next task. The Button is right-aligned to signal that the flow is moving forward. If there are more tasks, use the word “Next” followed by [ArrowForwardIcon](/components/icon). If the customer is on the last task, the Button should indicate they are finishing the goal, and not include the arrow icon.
- A secondary, right-aligned Button with the word “Cancel” if customers can’t save their progress, or “Close” if they can. Follow the [confirmation pattern](/patterns/confirmation) for guidance on how to ask a customer to confirm that they want to leave a Wizard or save their progress.
- A secondary, right-aligned Button with the word “Cancel” if customers can’t save their progress, or “Close” if they can. Follow the [confirmation pattern](/patterns/confirmation) for guidance on how to ask a customer to confirm that they want to leave a wizard or save their progress.
- A secondary, left-aligned back Button. If there were previous tasks, use the [ArrowBackIcon](/components/icon) followed by the word “Back”. If there are no previous tasks, don’t show the Button.

If the task contents don’t fill the width of the page body, use a [Separator](/components/separator) above the actions with a gap of `space-50`. However this should be used sparingly because in most cases your content should fill the width of the page body.
Expand All @@ -151,11 +151,11 @@ Don’t disable any footer Buttons unless it’s immediately obvious to customer
code={WizardFullPageExample}
/>

Use the full-page Wizard template when it’s absolutely critical that a customer remains focused to finish the task.
Use the full-page wizard template when it’s absolutely critical that a customer remains focused to finish the task.

If your app allows it, load the Wizard without a Sidebar, and replace the content in the Topbar with:
If your app allows it, load the wizard without a Sidebar, and replace the content in the Topbar with:

- The Wizard title as a left-aligned [Heading](/components/heading)
- The wizard title as a left-aligned [Heading](/components/heading)
- A secondary, right-aligned Button with the word “Cancel” if customers can’t save their progress, or “Close” if they can. Follow the [confirmation pattern](/patterns/confirmation) for guidance on how to ask a customer to confirm that they want to leave a Wizard or save their progress.

If your app doesn’t allow loading a page without the navigation frame, [collapse the Sidebar](/components/sidebar#compact-push-sidebar) and follow the [default Wizard template](#default-template).
Expand All @@ -166,11 +166,11 @@ At the top of the page, add the Task [Heading](/components/heading) and if neede

#### Body

Follow the [default Wizard template](#default-template).
Follow the [default wizard template](#default-template).

#### Actions footer

Follow the [default Wizard template](#default-template), but don’t include a close button in the footer.
Follow the [default wizard template](#default-template), but don’t include a close button in the footer.

### When to use Progress Steps

Expand All @@ -180,7 +180,7 @@ Only use [Progress Steps](/components/progress-steps) when necessary. Some scena
- A goal takes a long time to finish.
- A customer is trying a feature out or going through more of an exploratory flow. Progress Steps can help them understand if they want to complete the steps.

If the customer’s journey through a Wizard is relatively linear, continuous, and short, don’t use Progress Steps.
If the customer’s journey through a wizard is relatively linear, continuous, and short, don’t use Progress Steps.

When in doubt, start by not using Progress Steps, and add it in once it’s clear the experience suffers without it.

Expand All @@ -193,7 +193,7 @@ Match Progress Steps labels to task headings for each page. If you need to use P

#### With the default template

Place Progress Steps above the Wizard title.
Place Progress Steps above the wizard title.

<StoryPreview
title="Wizard page template - default header with progress steps"
Expand Down
Loading

0 comments on commit 337587d

Please sign in to comment.