diff --git a/.changeset/warm-clouds-drive.md b/.changeset/warm-clouds-drive.md new file mode 100644 index 00000000000..c250c30660f --- /dev/null +++ b/.changeset/warm-clouds-drive.md @@ -0,0 +1,6 @@ +--- +'@shopify/polaris': patch +'polaris.shopify.com': patch +--- + +Migrate content to polaris.shopify.com, automate example titles diff --git a/polaris-react/src/components/AccountConnection/README.md b/polaris-react/src/components/AccountConnection/README.md index cc43b416949..efb841054a5 100644 --- a/polaris-react/src/components/AccountConnection/README.md +++ b/polaris-react/src/components/AccountConnection/README.md @@ -96,7 +96,7 @@ Connect to app ## Examples -### Default account connection +### Default Use to let merchants connect or disconnect their store to their third-party accounts, like Facebook. diff --git a/polaris-react/src/components/ActionList/README.md b/polaris-react/src/components/ActionList/README.md index 66ac040a872..5b81acab043 100644 --- a/polaris-react/src/components/ActionList/README.md +++ b/polaris-react/src/components/ActionList/README.md @@ -80,7 +80,7 @@ Each item in an action list should be scannable avoiding unnecessary words and a ## Examples -### Action list in a popover +### In a popover Use for the least important actions so merchants aren’t distracted by secondary tasks. Can also be used for a set of actions that won’t fit in the available screen space. @@ -133,7 +133,7 @@ function ActionListInPopoverExample() { } ``` -### Action list with icons or image +### With icons or image Use when the items benefit from an associated action or image, such as a list of products. @@ -170,7 +170,7 @@ function ActionListWithMediaExample() { } ``` -### Action list with an icon and a suffix +### With an icon and a suffix Use when the items benefit from an associated action or image, such as a list of products. @@ -212,7 +212,7 @@ function ActionListWithSuffixExample() { } ``` -### Sectioned action list +### With sections Use when the items benefit from sections to help differentiate actions. @@ -261,7 +261,7 @@ function SectionedActionListExample() { } ``` -### Action list with destructive item +### With destructive item Use to visually indicate that an action list item is destructive. @@ -312,7 +312,7 @@ function ActionListWithDestructiveItemExample() { } ``` -### Action list with help text +### With help text Use help text when the normal Verb noun syntax for the actions does not provide sufficient context for the merchant. @@ -359,7 +359,7 @@ function ActionListWithHelpTextExample() { } ``` -### Action list with a prefix and a suffix +### With a prefix and a suffix Use help text when the normal Verb noun syntax for the actions does not provide sufficient context for the merchant. diff --git a/polaris-react/src/components/AppProvider/README.md b/polaris-react/src/components/AppProvider/README.md index fe1bc4768dc..edcfe497dd4 100644 --- a/polaris-react/src/components/AppProvider/README.md +++ b/polaris-react/src/components/AppProvider/README.md @@ -200,7 +200,7 @@ function AppProviderLinkExample() { ### With color scheme -With a `colorScheme`, the app provider component will set the root color scheme for the App (such as: light or dark).For `colorScheme` configuration, see the [CustomProperties](https://polaris.shopify.com/components/custom-properties) component documentation. +With a `colorScheme`, the app provider component will set the root color scheme for the App (such as light or dark). For `colorScheme` configuration, see the [CustomProperties](https://polaris.shopify.com/components/custom-properties) component documentation. ```jsx function AppProviderThemeExample() { diff --git a/polaris-react/src/components/Autocomplete/README.md b/polaris-react/src/components/Autocomplete/README.md index a6f1222cf90..99a84c809f6 100644 --- a/polaris-react/src/components/Autocomplete/README.md +++ b/polaris-react/src/components/Autocomplete/README.md @@ -34,7 +34,7 @@ The input field for autocomplete should follow the [content guidelines](https:// ## Examples -### Basic autocomplete +### Default Use to help merchants complete text input quickly from a list of options. @@ -107,7 +107,7 @@ function AutocompleteExample() { } ``` -### Multiple tags autocomplete +### With multiple tags Use to help merchants select multiple options from a list curated by the text input. @@ -210,7 +210,7 @@ function MultiAutocompleteExample() { } ``` -### Multiple sections autocomplete +### With multiple sections Use to help merchants complete text input quickly from a multiple sections list of options. @@ -314,7 +314,7 @@ function AutocompleteExample() { } ``` -### Autocomplete with loading +### With loading Use to indicate loading state to merchants while option data is processing. @@ -395,7 +395,7 @@ function AutocompleteExample() { } ``` -### Autocomplete with lazy loading +### With lazy loading ```jsx function AutoCompleteLazyLoadExample() { @@ -524,7 +524,7 @@ function AutoCompleteLazyLoadExample() { } ``` -### Autocomplete with empty state +### With empty state Use to indicate there are no search results. @@ -615,7 +615,7 @@ function AutocompleteExample() { } ``` -### Autocomplete with action +### With action Use to help merchants complete an action quickly. @@ -708,7 +708,7 @@ function AutocompleteActionBeforeExample() { } ``` -### Autocomplete with wrapping action +### With wrapping action Use to help merchants complete an action quickly with wrapping lines of text. @@ -803,7 +803,7 @@ function AutocompleteActionBeforeExample() { } ``` -### Autocomplete with destructive action +### With destructive action Use to help merchants complete a destructive action quickly. diff --git a/polaris-react/src/components/Avatar/README.md b/polaris-react/src/components/Avatar/README.md index cef246481d7..5d7150063fb 100644 --- a/polaris-react/src/components/Avatar/README.md +++ b/polaris-react/src/components/Avatar/README.md @@ -50,7 +50,7 @@ For avatars, we recommend using a format that describes what will show in the im ## Examples -### Default avatar +### Default Use to present an avatar for a merchant, customer, or business. @@ -58,7 +58,7 @@ Use to present an avatar for a merchant, customer, or business. ``` -### Extra small avatar +### Extra small Use to present an avatar in a condensed layout, such as a data table cell or an action list item. @@ -95,7 +95,7 @@ function ExtraSmallAvatarExample() { } ``` -### Square avatar +### Square Use a `square` shape when the avatar represents a non-person entity like an app, channel, or store. diff --git a/polaris-react/src/components/Badge/README.md b/polaris-react/src/components/Badge/README.md index 70a94711355..c7c2f2be6bc 100644 --- a/polaris-react/src/components/Badge/README.md +++ b/polaris-react/src/components/Badge/README.md @@ -73,7 +73,7 @@ Don’t use alternatives to existing badge options. Only create a new badge opti ## Examples -### Default badge +### Default Use to give a non-critical status update on a piece of information or action. @@ -81,7 +81,7 @@ Use to give a non-critical status update on a piece of information or action. Fulfilled ``` -### Small badge +### Small Use in layouts with minimal space, like inside of an `IndexTable` cell. @@ -89,7 +89,7 @@ Use in layouts with minimal space, like inside of an `IndexTable` cell. Fulfilled ``` -### Informational badge +### Informational Use to call out an object or action as having an important attribute. For example, marking an option as “Recommended” or marking a theme as “Published”. @@ -97,7 +97,7 @@ Use to call out an object or action as having an important attribute. For exampl Published ``` -### Success badge +### Success Use to indicate a successful, completed, or desirable state when it’s important to provide positive reinforcement to merchants. For example, when merchants successfully dispute a chargeback, a success badge shows that says “Funds recovered”. @@ -105,7 +105,7 @@ Use to indicate a successful, completed, or desirable state when it’s importan Funds recovered ``` -### Attention badge +### Attention Use when something requires merchants’ attention but the issue isn’t critical. For example, this badge would show next to an order that needs to be reviewed by merchants. @@ -113,27 +113,23 @@ Use when something requires merchants’ attention but the issue isn’t critica Inactive ``` -### Warning badge +### Warning -Use for critical and time-sensitive issues that require merchants’ attention and potential action. Warning events are often reversible. - -Keep in mind that seeing this badge can feel stressful for merchants so it should only be used when absolutely necessary. +Use for warnings and time-sensitive issues that require merchants’ attention and potential action. Warning events are often reversible. Keep in mind that seeing this badge can feel stressful for merchants so it should only be used when absolutely necessary. ```jsx Expired ``` -### Critical badge - -Use for critical and irreversible issues that require merchants’ attention and potential action. +### Critical -Keep in mind that seeing this badge can feel stressful for merchants so it should only be used when absolutely necessary. +Use for critical and irreversible issues that require merchants’ attention and potential action. Keep in mind that seeing this badge can feel stressful for merchants so it should only be used when absolutely necessary. ```jsx Action required ``` -### Incomplete badge +### Incomplete Use to indicate when a given task has not yet been completed. For example, when merchants haven’t fulfilled an order. @@ -143,7 +139,7 @@ Use to indicate when a given task has not yet been completed. For example, when ``` -### Partially complete badge +### Partially complete Use to indicate when a given task has been partially completed. For example, when merchants have partially fulfilled an order. @@ -153,7 +149,7 @@ Use to indicate when a given task has been partially completed. For example, whe ``` -### Complete badge +### Complete Use to indicate when a given task has been completed. For example, when merchants have fulfilled an order. @@ -161,7 +157,7 @@ Use to indicate when a given task has been completed. For example, when merchant Fulfilled ``` -### Badge with statusAndProgressLabelOverride +### With statusAndProgressLabelOverride Use when the status and progress accessibilityLabels are not appropriate to a given context. diff --git a/polaris-react/src/components/Banner/README.md b/polaris-react/src/components/Banner/README.md index 13c3a620025..36609516f05 100644 --- a/polaris-react/src/components/Banner/README.md +++ b/polaris-react/src/components/Banner/README.md @@ -201,10 +201,9 @@ To buy a shipping label, you must enter the total weight of your shipment, inclu ## Examples -### Default banners +### Default -- Use to convey general information or actions that aren’t critical. For example, you might show a banner that asks for merchant feedback. -- Default banners contain lower priority information and should always be dismissible. +Use to convey general information or actions that aren’t critical. For example, you might show a banner that asks for merchant feedback. Default banners contain lower priority information and should always be dismissible. ```jsx {}}> @@ -212,7 +211,7 @@ To buy a shipping label, you must enter the total weight of your shipment, inclu ``` -### Dismissible banner +### Dismissible Make all banners dismissible, unless they contain critical information or an important action that merchants are required to take. @@ -225,7 +224,7 @@ Make all banners dismissible, unless they contain critical information or an imp ``` -### Banner with footer call-to-action +### With footer call-to-action Use when you want merchants to take an action after reading the banner. @@ -244,7 +243,7 @@ Use when you want merchants to take an action after reading the banner. ``` -### Informational banners +### Informational Use to update merchants about a change or give them advice. @@ -260,10 +259,9 @@ Use to update merchants about a change or give them advice. ``` -### Success banner +### Success -- Default to using toasts for success messages, unless the feedback is delayed, persistent, or has a call to action -- Include next steps if applicable +Default to using toasts for success messages, unless the feedback is delayed, persistent, or has a call to action. Include next steps if applicable. ```jsx ``` -### Warning banners +### Warning -- Use to display information that needs attention or that merchants need to take action on -- Seeing these banners can be stressful for merchants so be cautious about using them +Use to display information that needs attention or that merchants need to take action on. Seeing these banners can be stressful for merchants so be cautious about using them. ```jsx ``` -### Critical banners +### Critical -- Use to communicate problems that have to be resolved immediately for merchants to complete a task -- For example, you will show this banner for orders with high fraud risk -- Seeing these banners can be stressful for merchants so be cautious about using them +Use to communicate problems that have to be resolved immediately for merchants to complete a task. For example, you will show this banner for orders with high fraud risk. Seeing these banners can be stressful for merchants so be cautious about using them. ```jsx ``` -### Banner in a modal +### In a modal Banners inside of modals render with less spacing and a pared-back design to fit within a content context. @@ -362,7 +357,7 @@ function BannerInModalExample() { } ``` -### Banner with focus +### With focus Banner can programmatically receive focus. Use this functionality to draw the merchant’s attention to the banner. @@ -388,7 +383,7 @@ function BannerWithFocusExample() { } ``` -### Banner in a card +### In a card Banners inside of cards render with less spacing and a pared-back design to fit within a content context. diff --git a/polaris-react/src/components/Button/README.md b/polaris-react/src/components/Button/README.md index 4bb7587d83a..1d51ad5b66c 100644 --- a/polaris-react/src/components/Button/README.md +++ b/polaris-react/src/components/Button/README.md @@ -62,7 +62,7 @@ Buttons should follow the content guidelines for [buttons](https://polaris.shopi ## Examples -### Basic button +### Default Used most in the interface. Only use another style if a button requires more or less visual weight. @@ -70,7 +70,7 @@ Used most in the interface. Only use another style if a button requires more or ``` -### Outline button +### Outline Use against shaded or colorful backgrounds. An outline button will maintain the appropriate visual weight and won’t clash with the background color. @@ -78,7 +78,7 @@ Use against shaded or colorful backgrounds. An outline button will maintain the ``` -### Outline monochrome button +### Outline monochrome Use against shaded or colorful backgrounds where matching the current text colors is more appropriate than the current outline theme. @@ -90,7 +90,7 @@ Use against shaded or colorful backgrounds where matching the current text color ``` -### Plain button +### Plain Use for less important or less commonly used actions since they’re less prominent. For example, plain buttons are used as actions in cards. @@ -98,7 +98,7 @@ Use for less important or less commonly used actions since they’re less promin ``` -### Plain monochrome button +### Plain monochrome Use for less important or less commonly used actions where matching the current text color is desired. For example in the InlineError component. @@ -111,7 +111,7 @@ Use for less important or less commonly used actions where matching the current ``` -### Plain destructive button +### Plain destructive Use for actions that will delete merchant data or be otherwise difficult to recover from. Since they’re less prominent, use for less important or less commonly used destructive actions. For example, plain buttons are used as actions in cards. @@ -121,7 +121,7 @@ Use for actions that will delete merchant data or be otherwise difficult to reco ``` -### Primary button +### Primary Use to highlight the most important actions in any experience. Don’t use more than one primary button in a section or screen to avoid overwhelming merchants. @@ -129,7 +129,7 @@ Use to highlight the most important actions in any experience. Don’t use more ``` -### Destructive button +### Destructive Use when the action will delete merchant data or be otherwise difficult to recover from. Destructive buttons should trigger a confirmation dialog before the action is completed. Be thoughtful about using destructive buttons because they can feel stressful for merchants. @@ -137,7 +137,7 @@ Use when the action will delete merchant data or be otherwise difficult to recov ``` -### Slim button +### Slim Use when a table or list has a set of actions on each item to avoid making items taller than they need to be. Don’t use slim buttons for primary actions. @@ -145,7 +145,7 @@ Use when a table or list has a set of actions on each item to avoid making items ``` -### Large button +### Large Use for the main call to action in empty states or for calls to action shown with large illustrations. @@ -153,7 +153,7 @@ Use for the main call to action in empty states or for calls to action shown wit ``` -### Full-width button +### Full-width Use for buttons placed in a narrow column (especially when stacking multiple buttons) or for creating a set of buttons of equal width. Full-width buttons should rarely exceed 320 px wide. @@ -161,7 +161,7 @@ Use for buttons placed in a narrow column (especially when stacking multiple but ``` -### Text-aligned button +### Text-aligned Use for plain or monochrome buttons that could have a long length and should be aligned when they potentially overflow onto the next line. @@ -173,7 +173,7 @@ Use for plain or monochrome buttons that could have a long length and should be ``` -### Pressed button +### Pressed Buttons are sometimes used as a toggle for other parts of the user interface. @@ -204,7 +204,7 @@ function PressedButton() { } ``` -### Plain disclosure button +### Plain disclosure Use to indicate that more content can be disclosed on click, like text in a collapsible. @@ -249,7 +249,7 @@ function RightAlignedDisclosureButton() { } ``` -### Select disclosure button +### Select disclosure Use to indicate that multiple options are available from this control, similar to a `` HTML element. - fileName: button-split.tsx - title: Split button - description: >- - Use when there is only one primary action but other related actions can be - taken. + title: Split + description: Use when there is only one primary action but other related actions can be taken. - fileName: button-disabled-state.tsx title: Disabled state - description: >- - Use for actions that aren’t currently available. The surrounding interface - should make it clear why the button is disabled and what needs to be done - to enable it. + description: Use for actions that aren’t currently available. The surrounding interface should make it clear why the button is disabled and what needs to be done to enable it. - fileName: button-loading-state.tsx title: Loading state - description: >- - Use when a button has been pressed and the associated action is in - progress. + description: Use when a button has been pressed and the associated action is in progress. --- # Button diff --git a/polaris.shopify.com/content/components/callout-card.md b/polaris.shopify.com/content/components/callout-card.md index 3d0c22dd346..7045b2f80bf 100644 --- a/polaris.shopify.com/content/components/callout-card.md +++ b/polaris.shopify.com/content/components/callout-card.md @@ -23,20 +23,14 @@ keywords: - illustration card examples: - fileName: callout-card-default.tsx - title: Default callout card - description: >- - Use to let merchants know about a feature or opportunity where there is a - clear, single action they need to take to move to the next step. + title: Default + description: Use to let merchants know about a feature or opportunity where there is a clear, single action they need to take to move to the next step. - fileName: callout-card-with-secondary-action.tsx - title: Callout card with secondary action - description: >- - Use to let merchants know about a feature or opportunity where there are - two distinct actions they can take on the information. + title: With secondary action + description: Use to let merchants know about a feature or opportunity where there are two distinct actions they can take on the information. - fileName: callout-card-dismissable.tsx - title: Dismissable callout card - description: >- - Make all callout cards dismissible so merchants can get rid of cards about - features they’re not interested in. + title: Dismissable + description: Make all callout cards dismissible so merchants can get rid of cards about features they’re not interested in. --- # Callout card diff --git a/polaris.shopify.com/content/components/caption.md b/polaris.shopify.com/content/components/caption.md index 8fff1ce4a6a..a9c66db8c84 100644 --- a/polaris.shopify.com/content/components/caption.md +++ b/polaris.shopify.com/content/components/caption.md @@ -16,10 +16,8 @@ keywords: - small text examples: - fileName: caption-default.tsx - title: Default caption - description: >- - Use to provide details in situations where content is compact and space is - tight. + title: Default + description: Use to provide details in situations where content is compact and space is tight. --- # Caption diff --git a/polaris.shopify.com/content/components/card.md b/polaris.shopify.com/content/components/card.md index bd6b007fa9c..3581fcaafdb 100644 --- a/polaris.shopify.com/content/components/card.md +++ b/polaris.shopify.com/content/components/card.md @@ -21,85 +21,55 @@ keywords: - call out examples: - fileName: card-default.tsx - title: Default card - description: >- - Use when you have a simple message to communicate to merchants that - doesn’t require any secondary steps. + title: Default + description: Use when you have a simple message to communicate to merchants that doesn’t require any secondary steps. - fileName: card-with-header-actions.tsx - title: Card with header actions - description: >- - Use for less important card actions, or actions merchants may do before - reviewing the contents of the card. For example, merchants may want to add - items to a card containing a long list, or enter a customer’s new - address.Use for less important card actions, or actions merchants may do - before reviewing the contents of the card.Use an icon for the action, if - possibleInclude no more than 2 actions + title: With header actions + description: Use for less important card actions, or actions merchants may do before reviewing the contents of the card. For example, merchants may want to add items to a card containing a long list, or enter a customer’s new address. - fileName: card-with-footer-actions.tsx - title: Card with footer actions - description: >- - Use footer actions for a card’s most important actions, or actions - merchants should do after reviewing the contents of the card.Use buttons - with labelsIf you have more than 2 actions, consider using an overflow - menu on the card + title: With footer actions + description: Use footer actions for a card’s most important actions, or actions merchants should do after reviewing the contents of the card. For example, merchants should review the contents of a shipment before an important action like adding tracking information. Footer actions can be left or right aligned with the `footerActionAlignment` prop. - fileName: card-with-multiple-footer-actions.tsx - title: Card with multiple footer actions + title: With multiple footer actions + description: When multiple secondary footer actions are provided, they will render in an action list popover activated by a disclosure button. The disclosure button text can be customized with the `secondaryFooterActionsDisclosureText` prop. - fileName: card-with-custom-footer-actions.tsx - title: Card with custom footer actions - description: >- - Use to present actionable content that is optional or not the primary - purpose of the page. + title: With custom footer actions + description: Use to present actionable content that is optional or not the primary purpose of the page. - fileName: card-with-destructive-footer-action.tsx - title: Card with destructive footer action - description: >- - Use when a card action will delete merchant data or be otherwise difficult - to recover from. + title: With destructive footer action + description: Use when a card action will delete merchant data or be otherwise difficult to recover from. - fileName: card-with-multiple-sections.tsx - title: Card with multiple sections - description: >- - Use when you have two related but distinct pieces of information to - communicate to merchants. Multiple sections can help break up complicated - concepts to make them easier to scan and understand. + title: With multiple sections + description: Use when you have two related but distinct pieces of information to communicate to merchants. Multiple sections can help break up complicated concepts to make them easier to scan and understand. - fileName: card-with-multiple-titled-sections.tsx - title: Card with multiple titled sections - description: >- - Use when you have two related but distinct pieces of information to - communicate to merchants that are complex enough to require a title to - introduce them. - - fileName: card-section-with-action.tsx - title: Card section with action + title: With multiple titled sections + description: Use when you have two related but distinct pieces of information to communicate to merchants that are complex enough to require a title to introduce them. + - fileName: card-with-sections-and-actions.tsx + title: With sections and actions description: Use when your card section has actions that apply only to that section. - fileName: card-with-subsection.tsx - title: Card with subsection + title: With subsection description: Use when your card sections need further categorization. - - fileName: card-section-with-destructive-action.tsx - title: Card section with destructive action - description: >- - Use when a card action applies only to one section and will delete - merchant data or be otherwise difficult to recover from. + - fileName: card-with-destructive-action.tsx + title: With destructive action + description: Use when a card action applies only to one section and will delete merchant data or be otherwise difficult to recover from. - fileName: card-with-a-subdued-section.tsx - title: Card with a subdued section - description: >- - Use to indicate when one of the sections in your card contains inactive or - disabled content. - - fileName: card-subdued-for-secondary-content.tsx - title: Subdued card for secondary content - description: >- - Use for content that you want to deprioritize. Subdued cards don’t stand - out as much as cards with white backgrounds so don’t use them for - information or actions that are critical to merchants. + title: With a subdued section + description: Use to indicate when one of the sections in your card contains inactive or disabled content. + - fileName: card-with-subdued-for-secondary-content.tsx + title: With subdued for secondary content + description: Use for content that you want to deprioritize. Subdued cards don’t stand out as much as cards with white backgrounds so don’t use them for information or actions that are critical to merchants. - fileName: card-with-separate-header.tsx - title: Card with separate header + title: With separate header description: Use to be able to use custom React elements as header content. - - fileName: card-section-with-custom-react-node-title.tsx - title: Card section with custom React Node title - description: >- - Use to render custom content such as icons, links, or buttons in a card - section’s header. - - fileName: card-with-all-of-its-elements.tsx - title: Card with all of its elements + - fileName: card-with-custom-react-node-title.tsx + title: With custom React Node title + description: Use to render custom content such as icons, links, or buttons in a card section’s header. + - fileName: card-with-all-elements.tsx + title: With all elements description: Use as a broad example that includes most props available to card. - fileName: card-with-flushed-sections.tsx - title: Card with flushed sections + title: With flushed sections description: Use when you need further control over the spacing of your card sections. --- diff --git a/polaris.shopify.com/content/components/checkbox.md b/polaris.shopify.com/content/components/checkbox.md index 5b3a62ea270..b79604c8f3e 100644 --- a/polaris.shopify.com/content/components/checkbox.md +++ b/polaris.shopify.com/content/components/checkbox.md @@ -14,12 +14,9 @@ keywords: - form selections - multi-choice lists examples: - - fileName: checkboxes-default.tsx - title: Default checkboxes - description: >- - Use in forms to toggle the state of something on or off. Default - checkboxes can appear in two states: selected and disabled, or - unselected. + - fileName: checkbox-default.tsx + title: Default + description: Use in forms to toggle the state of something on or off. Default checkboxes can appear as selected and disabled, or unselected. --- # Checkbox @@ -33,8 +30,7 @@ Checkboxes are most commonly used to give merchants a way to make a range of sel Checkboxes should: - Work independently from each other: selecting one checkbox shouldn’t change the selection status of another checkbox in the list. The exception is when a checkbox is used to make a bulk selection of multiple items. -- Be framed positively: for example, `Turn on notifications` instead of - `Turn off notifications` +- Be framed positively: for example, `Turn on notifications` instead of `Turn off notifications` - Always have a label when being used to toggling a setting on or off - Be listed according to a logical order, whether it’s alphabetical, numerical, time-based, or some other clear system. - Link to more information or include a subtitle as required to provide more explanation. Don’t rely on tooltips to explain a checkbox. diff --git a/polaris.shopify.com/content/components/choice-list.md b/polaris.shopify.com/content/components/choice-list.md index 69f6c41ebff..9e3f2b6f680 100644 --- a/polaris.shopify.com/content/components/choice-list.md +++ b/polaris.shopify.com/content/components/choice-list.md @@ -18,43 +18,26 @@ keywords: - multi-choice list - single-choice list examples: - - fileName: choice-list-single.tsx - title: Single choice list - description: >- - Allows merchants to select one option from a list.Make sure all options - are an either/or choice. - - fileName: choice-list-single-with-error.tsx - title: Single choice list with error - description: >- - Allows for accessible error handling by connecting the error message to - the field with the error. - - fileName: choice-list-multi.tsx - title: Multi-choice list - description: >- - Allows merchants to select multiple options from a list.Avoid options that - are an either/or choice. - - fileName: >- - choice-list-single-choice-or-multi-with-children-content-always-rendered.tsx - title: Single-choice or multi-choice list with children content (always rendered) - description: >- - Use when you need merchants to view and/or interact with additional - content under a choice. The content will always be rendered. Works for - both single-choice and multi-choice list. - - fileName: >- - choice-list-single-choice-or-multi-with-children-content-only-rendered-when-choice-is-selected.tsx - title: >- - Single-choice or multi-choice list with children content (only rendered - when choice is selected) - description: >- - Use when you need merchants to view and/or interact with additional - content under a choice. The content is only rendered when the choice is - selected. Works for both single-choice and multi-choice list. + - fileName: choice-list-default.tsx + title: Default + description: Allows merchants to select one option from a list. Make sure all options are an either/or choice. + - fileName: choice-list-with-error.tsx + title: With error + description: Allows for accessible error handling by connecting the error message to the field with the error. + - fileName: choice-list-with-multi-choice.tsx + title: With multi-choice + description: Allows merchants to select multiple options from a list. Avoid options that are an either/or choice. + - fileName: choice-list-with-children-content.tsx + title: With children content + description: Use when you need merchants to view and/or interact with additional content under a choice. The content will always be rendered. + - fileName: choice-list-with-dynamic-children-content.tsx + title: With dynamic children content + description: Use when you need merchants to view and/or interact with additional content under a choice. The content is only rendered when the choice is selected. Works for both single-choice and multi-choice list. --- # Choice list -A choice list lets you create a list of grouped radio buttons or checkboxes. -Use this component if you need to group together a related list of interactive choices. +A choice list lets you create a list of grouped radio buttons or checkboxes. Use this component if you need to group together a related list of interactive choices. --- @@ -113,14 +96,14 @@ Shipping Options #### Do -If the customer abandons their checkout, send them an email reminder to complete their order +If the customer abandons their checkout, send them an email reminder to complete their order: - Option a - Option b #### Don’t -If the customer abandons their checkout, send them an email reminder to complete their order: +If the customer abandons their checkout, send them an email reminder to complete their order - Option a - Option b diff --git a/polaris.shopify.com/content/components/collapsible.md b/polaris.shopify.com/content/components/collapsible.md index e7f0578864e..24171e145d5 100644 --- a/polaris.shopify.com/content/components/collapsible.md +++ b/polaris.shopify.com/content/components/collapsible.md @@ -20,10 +20,8 @@ keywords: - collapse examples: - fileName: collapsible-default.tsx - title: Default collapsible component - description: >- - Use for a basic “show more” interaction when you need to display more - content. + title: Default + description: Use for a basic “show more” interaction when you need to display more content. --- # Collapsible diff --git a/polaris.shopify.com/content/components/color-picker.md b/polaris.shopify.com/content/components/color-picker.md index ebd020ce8aa..61e88fc099e 100644 --- a/polaris.shopify.com/content/components/color-picker.md +++ b/polaris.shopify.com/content/components/color-picker.md @@ -15,17 +15,14 @@ keywords: - alpha value selector examples: - fileName: color-picker-default.tsx - title: Default color picker - description: |- - Use when merchants need to select a color to make the selection a visual task rather than a technical one. - - fileName: color-pickerpicker-with-transparent-value.tsx - title: Colorpicker with transparent value - description: >- - Use when attached to a visual builder to allow the designated object to have a transparent background that allows underlying objects to show through. - - fileName: color-pickerpicker-with-transparent-value-full-width.tsx - title: Colorpicker with transparent value full width - description: >- - Use when attached to a visual builder to allow the designated object to have a transparent background that allows underlying objects to show through. + title: Default + description: Use when merchants need to select a color to make the selection a visual task rather than a technical one. + - fileName: color-picker-with-transparent-value.tsx + title: With transparent value + description: Use when attached to a visual builder to allow the designated object to have a transparent background that allows underlying objects to show through. + - fileName: color-picker-with-transparent-value-full-width.tsx + title: With transparent value full width + description: Use when attached to a visual builder to allow the designated object to have a transparent background that allows underlying objects to show through. --- # Color picker @@ -38,4 +35,3 @@ The color picker is used to let merchants select a color visually. For example, - Use the alpha slider if you want to allow merchants to be able to select a transparent color ---- diff --git a/polaris.shopify.com/content/components/combobox.md b/polaris.shopify.com/content/components/combobox.md index 28f39f4c3a1..6c87bb7f5fc 100644 --- a/polaris.shopify.com/content/components/combobox.md +++ b/polaris.shopify.com/content/components/combobox.md @@ -10,21 +10,23 @@ keywords: - listbox - list box examples: - - fileName: combobox-single-select-autocomplete.tsx - title: Single select autocomplete - description: >- - Use when merchants can select one option from a predefined or editable - list. - - fileName: combobox-multi-select-autocomplete.tsx - title: Multi-select autocomplete - description: >- - Use when merchants can select one or more options from a predefined or - editable list. - - fileName: combobox-multi-select-autocomplete-with-vertical-content.tsx - title: Multi-select autocomplete with vertical content + - fileName: combobox-default.tsx + title: Default + description: Use when merchants can select one option from a predefined or editable list. + - fileName: combobox-with-manual-selection.tsx + title: With manual selection + description: Use when merchants can select one option from a predefined or editable list. + - fileName: combobox-with-multi-select.tsx + title: With multi-select + description: Use when merchants can select one or more options from a predefined or editable list. + - fileName: combobox-with-multi-select-and-manual-selection.tsx + title: With multi-select and manual selection + description: Use when merchants can select one or more options from a predefined or editable list. + - fileName: combobox-with-multi-select-and-vertical-content.tsx + title: With multi-select and vertical content description: Use to display selected options above the input value. - - fileName: combobox-autocomplete-with-loading.tsx - title: Autocomplete with loading + - fileName: combobox-with-loading.tsx + title: With loading description: Use to indicate to merchants that the list data is being fetched. --- diff --git a/polaris.shopify.com/content/components/contextual-save-bar.md b/polaris.shopify.com/content/components/contextual-save-bar.md index adec4cb9adc..583d066a4b3 100644 --- a/polaris.shopify.com/content/components/contextual-save-bar.md +++ b/polaris.shopify.com/content/components/contextual-save-bar.md @@ -11,25 +11,14 @@ keywords: - logo examples: - fileName: contextual-save-bar-default.tsx - title: Default contextual save bar - description: >- - Use the save action to provide an opportunity to save changes. Use the - discard action to allow merchants the option to discard their changes. Use the message to provide helpful context on the nature of those changes. - - fileName: contextual-save-bar-during-creation.tsx - title: Contextual save bar during creation - description: >- - Use the save action to provide an opportunity to save a newly-created - resource. Use the discard action to allow merchants the option to discard a new resource. Use the message to provide helpful context on the nature of the new resource. + title: Default + description: Use the save action to provide an opportunity to save changes. Use the discard action to allow merchants the option to discard their changes. Use the message to provide helpful context on the nature of those changes. - fileName: contextual-save-bar-with-flush-contents.tsx - title: Contextual save bar with flush contents - description: >- - Use the alignContentFlush flag when you want to omit the logo from the - contextual save bar and repurpose that space to extend the message contents fully to the left side - of the container. - - fileName: contextual-save-bar-full-width.tsx - title: Contextual save bar full width - description: >- - Use the fullWidth flag when you want to remove the default max-width set on the contextual save bar. + title: With flush contents + description: Use the alignContentFlush flag when you want to omit the logo from the contextual save bar and repurpose that space to extend the message contents fully to the left side of the container. + - fileName: contextual-save-bar-with-full-width.tsx + title: With full width + description: Use the fullWidth flag when you want to remove the default max-width set on the contextual save bar. --- # Contextual Save Bar diff --git a/polaris.shopify.com/content/components/custom-properties.md b/polaris.shopify.com/content/components/custom-properties.md index 200f162dc5b..2aaf7b875a3 100644 --- a/polaris.shopify.com/content/components/custom-properties.md +++ b/polaris.shopify.com/content/components/custom-properties.md @@ -9,23 +9,14 @@ keywords: - dark mode examples: - fileName: custom-properties-rendered-by-the-app-provider.tsx - title: Custom properties rendered by the app provider - description: >- - The app provider component renders a CustomProperties component with the - default color scheme. + title: Rendered by the app provider + description: The app provider component renders a CustomProperties component with the default color scheme. - fileName: custom-properties-with-a-color-scheme-rendered-by-the-app-provider.tsx - title: Custom properties with a color scheme rendered by the app provider - description: >- - A color scheme can be passed to the app provider to determine what color - scheme is globally applied to the application. - - fileName: >- - custom-properties-with-a-different-color-scheme-nested-within-an-app-provider.tsx - title: >- - Custom properties with a different color scheme nested within an app - provider - description: >- - Custom properties can be nested within the custom properties rendered by - the app provider in order to override the color scheme at a local level. + title: With a color scheme rendered by the app provider + description: A color scheme can be passed to the app provider to determine what color scheme is globally applied to the application. + - fileName: custom-properties-with-a-different-color-scheme-nested-within-an-app-provider.tsx + title: With a different color scheme nested within an app provider + description: Custom properties can be nested within the custom properties rendered by the app provider in order to override the color scheme at a local level. --- # Custom Properties diff --git a/polaris.shopify.com/content/components/data-table.md b/polaris.shopify.com/content/components/data-table.md index e4ce74eca57..765f6bf8297 100644 --- a/polaris.shopify.com/content/components/data-table.md +++ b/polaris.shopify.com/content/components/data-table.md @@ -9,43 +9,35 @@ keywords: - index examples: - fileName: data-table-default.tsx - title: Default data table + title: Default description: Use to present small amounts of data for merchants to view statically. - fileName: data-table-sortable.tsx - title: Sortable data table - description: >- - Use when clarity of the table’s content is needed. For example, to note - the number of rows currently shown in a data table with pagination. + title: Sortable + description: Use when clarity of the table’s content is needed. For example, to note the number of rows currently shown in a data table with pagination. - fileName: data-table-with-footer.tsx - title: Data table with footer - description: >- - Use when clarity of the table’s content is needed. For example, to note - the number of rows currently shown in a data table with pagination. + title: With footer + description: Use when clarity of the table’s content is needed. For example, to note the number of rows currently shown in a data table with pagination. - fileName: data-table-with-custom-totals-heading.tsx - title: Data table with custom totals heading + title: With custom totals heading description: Use to provide a custom heading for the totals row. - fileName: data-table-with-totals-in-footer.tsx - title: Data table with totals in footer - description: >- - Use to reposition the totals row in a more appropriate location based on - the data stored in the - - table for merchants to better understand its meaning. + title: With totals in footer + description: Use to reposition the totals row in a more appropriate location based on the data stored in the table for merchants to better understand its meaning. - fileName: data-table-with-row-heading-links.tsx - title: Data table with row heading links + title: With row heading links description: Use to help merchants find relevant, finer grained data sets. - fileName: data-table-with-all-of-its-elements.tsx - title: Data table with all of its elements + title: With all of its elements description: Use as a broad example that includes most props available to data table. + - fileName: data-table-with-fixed-first-column.tsx + title: With fixed first column + description: Use when the table contains many columns and it would benefit the merchant to see the first column when scrolling to the right. - fileName: data-table-with-increased-density-and-zebra-striping.tsx - title: Data table with increased density and zebra striping + title: With increased density and zebra striping description: Use as a broad example that includes most props available to data table. - fileName: data-table-with-sticky-header-enabled.tsx - title: Data table with sticky header enabled + title: With sticky header enabled description: Use as a broad example that includes most props available to data table. - - fileName: data-table-with-fixed-first-column-enabled.tsx - title: Data table with fixed first column enabled - description: Use to fix the first column when horizontal scrolling becomes necessary. Keeps the context of the row as the user scrolls. --- # Data table diff --git a/polaris.shopify.com/content/components/date-picker.md b/polaris.shopify.com/content/components/date-picker.md index 09d57907900..b8bd96019fc 100644 --- a/polaris.shopify.com/content/components/date-picker.md +++ b/polaris.shopify.com/content/components/date-picker.md @@ -17,23 +17,19 @@ keywords: - date range selector examples: - fileName: date-picker-default.tsx - title: Default date picker - description: >- - Use when merchants need to select a single day close to today (today is - the default starting position for the date picker). + title: Default + description: Use when merchants need to select a single day close to today (today is the default starting position for the date picker). - fileName: date-picker-ranged.tsx - title: Ranged date picker - description: >- - Use when merchants need to select a range of days close to today (today is - the default starting position for the date picker). + title: Ranged + description: Use when merchants need to select a range of days close to today (today is the default starting position for the date picker). - fileName: date-picker-multi-month-ranged.tsx - title: Multi-month ranged date picker + title: Multi-month ranged description: Use multi-month mode to show two months at a time. - fileName: date-picker-with-disabled-date-ranges.tsx - title: Date picker with disabled date ranges + title: With disabled date ranges description: Date ranges may be disabed if you do not want them to be selectable - fileName: date-picker-with-specific-disabled-dates.tsx - title: Date picker with specific disabled dates + title: With specific disabled dates description: Dates may be disabed if you do not want them to be selectable --- diff --git a/polaris.shopify.com/content/components/description-list.md b/polaris.shopify.com/content/components/description-list.md index 3c6da80c82f..dd307cbd9ba 100644 --- a/polaris.shopify.com/content/components/description-list.md +++ b/polaris.shopify.com/content/components/description-list.md @@ -13,10 +13,8 @@ keywords: - term explaination examples: - fileName: description-list-default.tsx - title: Default description list - description: >- - Use when you need to present merchants with a list of items or terms - alongside descriptions and explanations. + title: Default + description: Use when you need to present merchants with a list of items or terms alongside descriptions and explanations. --- # Description list diff --git a/polaris.shopify.com/content/components/display-text.md b/polaris.shopify.com/content/components/display-text.md index 9b887c1e484..28f688c73aa 100644 --- a/polaris.shopify.com/content/components/display-text.md +++ b/polaris.shopify.com/content/components/display-text.md @@ -25,24 +25,16 @@ keywords: examples: - fileName: display-text-extra-large.tsx title: Extra large - description: >- - Use this size sparingly and never multiple times on the same - page. + description: Use this size sparingly and never multiple times on the same page. - fileName: display-text-large.tsx title: Large - description: >- - Use for display text that’s more important than the medium size, but less - important than extra large. + description: Use for display text that’s more important than the medium size, but less important than extra large. - fileName: display-text-medium.tsx title: Medium - description: >- - Use for display text that’s more important than the small size, but less - important than large. + description: Use for display text that’s more important than the small size, but less important than large. - fileName: display-text-small.tsx title: Small - description: >- - Use for text that would otherwise use body text, but that needs to scale - with other display text. + description: Use for text that would otherwise use body text, but that needs to scale with other display text. --- # Display text @@ -54,8 +46,7 @@ Display styles make a bold visual statement. Use them to create impact when the ## Best practices - Use when the primary goal of the page is communication rather than interaction. -- Use larger display text sizes when a page is focused around a single message. - In these cases it may be paired with an illustration. +- Use larger display text sizes when a page is focused around a single message. In these cases it may be paired with an illustration. - Use smaller display text to pair with larger text, or alone as part of more complex data displays such as dashboards. --- @@ -69,11 +60,9 @@ Display text should be: - Benefits-driven and focused on information that is most important to merchants - Concise and scannable: - Use simple, clear language that can be read at a glance - - Keep display text content to a short sentence that’s just a few words in - length + - Keep display text content to a short sentence that’s just a few words in length - Avoid using punctuation such as periods, commas, or semicolons - - Avoid using exclamation marks—display text already makes enough of a - statement without an exclamation mark + - Avoid using exclamation marks—display text already makes enough of a statement without an exclamation mark - Write in sentence case --- diff --git a/polaris.shopify.com/content/components/drop-zone.md b/polaris.shopify.com/content/components/drop-zone.md index d8fa5a70e09..8397fe9375e 100644 --- a/polaris.shopify.com/content/components/drop-zone.md +++ b/polaris.shopify.com/content/components/drop-zone.md @@ -13,51 +13,38 @@ keywords: - upload placeholder - drop placeholder examples: - - fileName: drop-zone-with-file-upload.tsx - title: Drop zone with file upload - description: >- - Use to allow merchants to upload files. They can drag and drop files into - the dashed area, or upload traditionally by clicking the “Add file” button - or anywhere inside the dashed area. + - fileName: drop-zone-default.tsx + title: Default + description: Use to allow merchants to upload files. They can drag and drop files into the dashed area, or upload traditionally by clicking the “Add file” button or anywhere inside the dashed area. - fileName: drop-zone-with-a-label.tsx - title: Drop zone with a label + title: With a label description: Use to pair with a label for better accessibility. - fileName: drop-zone-with-image-file-upload.tsx - title: Drop zone with image file upload + title: With image file upload description: Use for cases that accept image file formats. - fileName: drop-zone-with-single-file-upload.tsx - title: Drop zone with single file upload + title: With single file upload description: Use to accept only one file. - fileName: drop-zone-with-drop-on-page.tsx - title: Drop zone with drop on page + title: With drop on page description: Use to accept files for upload when dropped anywhere on the page. - fileName: drop-zone-accepts-only-svg-files.tsx - title: Drop zone accepts only SVG files + title: Accepts only SVG files description: Use to accept only SVG files. - fileName: drop-zone-nested.tsx - title: Nested drop zone - description: >- - Use to allow merchants to upload files in a wider area than the visible - drop zone. + title: Nested + description: Use to allow merchants to upload files in a wider area than the visible drop zone. - fileName: drop-zone-medium-sized.tsx - title: Medium-sized drop zone - description: >- - Use for cases with limited space. To improve usability, nest medium-sized - drop zone in a larger drop zone with no outline. See the nested dropzone - example. + title: Medium-sized + description: Use for cases with limited space. To improve usability, nest medium-sized drop zone in a larger drop zone with no outline. See the nested dropzone example. - fileName: drop-zone-small-sized.tsx - title: Small-sized drop zone - description: >- - Use for cases with tight space constraints, such as variant thumbnails on - the Product details page. To improve usability, nest small-sized drop zone - in a larger drop zone with no outline. See the nested dropzone example. + title: Small-sized + description: Use for cases with tight space constraints, such as variant thumbnails on the Product details page. To improve usability, nest small-sized drop zone in a larger drop zone with no outline. See the nested dropzone example. - fileName: drop-zone-with-custom-file-upload-text.tsx - title: Drop zone with custom FileUpload text - description: >- - Use for cases where you want the child contents of the dropzone to - determine its height. + title: With custom FileUpload text + description: Use for cases where you want the child contents of the dropzone to determine its height. - fileName: drop-zone-with-custom-file-dialog-trigger.tsx - title: Drop zone with custom file dialog trigger + title: With custom file dialog trigger description: Use to trigger the file dialog from an action somewhere else on the page. --- diff --git a/polaris.shopify.com/content/components/empty-state.md b/polaris.shopify.com/content/components/empty-state.md index 3bc4b424eed..dd255e27d97 100644 --- a/polaris.shopify.com/content/components/empty-state.md +++ b/polaris.shopify.com/content/components/empty-state.md @@ -22,18 +22,13 @@ keywords: - landing layouts examples: - fileName: empty-state-default.tsx - title: Default empty state - description: >- - Use to explain a single feature before merchants have used - it. + title: Default + description: Use to explain a single feature before merchants have used it. - fileName: empty-state-with-subdued-footer-context.tsx - title: Empty state with subdued footer context - description: >- - Use to provide additional but non-critical context for a new product or - feature. Can also be used to include a subdued call to action for - secondary or tertiary actions. + title: With subdued footer context + description: Use to provide additional but non-critical context for a new product or feature. Can also be used to include a subdued call to action for secondary or tertiary actions. - fileName: empty-state-with-full-width-layout.tsx - title: Empty state with full width layout + title: With full width layout --- # Empty state @@ -53,8 +48,7 @@ Empty states should: - Explain the steps merchants need to take to activate a product or feature - Use illustrations thoughtfully as outlined in our [illustration guidelines](https://polaris.shopify.com/design/illustrations) - Use only one primary call-to-action button -- Provide extra spacing at the bottom of an empty state that is within content - (card, modal, or navigation) to match the image that was passed into the component with a white space above it of 40px +- Provide extra spacing at the bottom of an empty state that is within content (card, modal, or navigation) to match the image that was passed into the component with a white space above it of 40px --- @@ -140,8 +134,7 @@ They should be: ### Secondary action -Secondary actions are used for less important actions such as “Learn more” or -“Close” buttons. They should follow all the other content rules outlined for primary buttons. +Secondary actions are used for less important actions such as “Learn more” or “Close” buttons. They should follow all the other content rules outlined for primary buttons. --- diff --git a/polaris.shopify.com/content/components/exception-list.md b/polaris.shopify.com/content/components/exception-list.md index 9c24f3ffebf..e15679fa621 100644 --- a/polaris.shopify.com/content/components/exception-list.md +++ b/polaris.shopify.com/content/components/exception-list.md @@ -7,8 +7,8 @@ keywords: - list - list exceptions examples: - - fileName: exception-list-with-icon.tsx - title: Exception list with icon + - fileName: exception-list-default.tsx + title: Default description: Use icons to add clarity or assist in visualizing the meaning --- diff --git a/polaris.shopify.com/content/components/filters.md b/polaris.shopify.com/content/components/filters.md index b02b5fe954b..a19b6b67d89 100644 --- a/polaris.shopify.com/content/components/filters.md +++ b/polaris.shopify.com/content/components/filters.md @@ -11,23 +11,23 @@ keywords: - table examples: - fileName: filters-with-a-resource-list.tsx - title: Filtering with a resource list + title: With a resource list - fileName: filters-with-a-data-table.tsx - title: Filtering with a data table + title: With a data table - fileName: filters-with-children-content.tsx - title: Filters with children content - - fileName: filters-all-disabled.tsx - title: All filters disabled + title: With children content + - fileName: filters-disabled.tsx + title: Disabled - fileName: filters-some-disabled.tsx - title: Some filters disabled + title: Some disabled - fileName: filters-without-clear-button.tsx - title: Filters without clear button + title: Without clear button - fileName: filters-with-help-text.tsx - title: Filters with help text + title: With help text - fileName: filters-with-query-field-hidden.tsx - title: Filters with query field hidden + title: With query field hidden - fileName: filters-with-query-field-disabled.tsx - title: Filters with query field disabled + title: With query field disabled --- # Filters @@ -153,4 +153,3 @@ If all tag pills selected: truncate in the middle ---- diff --git a/polaris.shopify.com/content/components/footer-help.md b/polaris.shopify.com/content/components/footer-help.md index 700318b4f38..1b0ae6890d4 100644 --- a/polaris.shopify.com/content/components/footer-help.md +++ b/polaris.shopify.com/content/components/footer-help.md @@ -14,11 +14,9 @@ keywords: - educating - teaching examples: - - fileName: footer-help-box.tsx - title: Footer help box - description: >- - Use to direct merchants to more information related to the product or - feature they’re working on. + - fileName: footer-help-default.tsx + title: Default + description: Use to direct merchants to more information related to the product or feature they’re working on. --- # Footer help diff --git a/polaris.shopify.com/content/components/form-layout.md b/polaris.shopify.com/content/components/form-layout.md index 3225fb5ce15..f22485c59c7 100644 --- a/polaris.shopify.com/content/components/form-layout.md +++ b/polaris.shopify.com/content/components/form-layout.md @@ -28,23 +28,14 @@ keywords: - layout input fields examples: - fileName: form-layout-default.tsx - title: Default form layout - description: >- - Use to stack form fields vertically, which makes them easier to scan and - complete. + title: Default + description: Use to stack form fields vertically, which makes them easier to scan and complete. - fileName: form-layout-field-group.tsx title: Field group - description: >- - Use field groups to arrange multiple fields in a row.Works best for - familiar layouts such as a row of city, state, and zip code fields. Use - caution when arranging unrelated fields next to each other as this makes - fields easier to miss.Field groups will wrap automatically on smaller - screens. + description: Use field groups to arrange multiple fields in a row. Works best for familiar layouts such as a row of city, state, and zip code fields. Use caution when arranging unrelated fields next to each other as this makes fields easier to miss. Field groups will wrap automatically on smaller screens. - fileName: form-layout-condensed-field-group.tsx title: Condensed field group - description: >- - For very short inputs, the width of the inputs may be reduced in order to - fit more fields in the row. + description: For very short inputs, the width of the inputs may be reduced in order to fit more fields in the row. --- # Form layout diff --git a/polaris.shopify.com/content/components/form.md b/polaris.shopify.com/content/components/form.md index 4c414444436..858fc8e971d 100644 --- a/polaris.shopify.com/content/components/form.md +++ b/polaris.shopify.com/content/components/form.md @@ -16,7 +16,7 @@ examples: title: Custom onSubmit description: Use onSubmit as a callback for when your form is submitted. - fileName: form-without-native-validation.tsx - title: Form without native validation + title: Without native validation description: Use in forms to toggle native form validation. --- diff --git a/polaris.shopify.com/content/components/frame.md b/polaris.shopify.com/content/components/frame.md index 337b99a741a..4a9a2f65292 100644 --- a/polaris.shopify.com/content/components/frame.md +++ b/polaris.shopify.com/content/components/frame.md @@ -17,13 +17,11 @@ keywords: - toast examples: - fileName: frame-in-an-application.tsx - title: Frame in an application + title: In an application description: Use to present the frame structure and all of its elements. - fileName: frame-with-an-offset.tsx - title: Frame with an offset - description: >- - Use to present the frame structure and all of its elements with an offset - provided to the theme. + title: With an offset + description: Use to present the frame structure and all of its elements with an offset provided to the theme. --- # Frame diff --git a/polaris.shopify.com/content/components/fullscreen-bar.md b/polaris.shopify.com/content/components/fullscreen-bar.md index 43c888fdfef..8b758bdbb3d 100644 --- a/polaris.shopify.com/content/components/fullscreen-bar.md +++ b/polaris.shopify.com/content/components/fullscreen-bar.md @@ -9,12 +9,10 @@ keywords: - app examples: - fileName: fullscreen-bar-with-children.tsx - title: Fullscreen bar with children - description: >- - Use to provide structure for the top of an application while in fullscreen - mode. + title: With children + description: Use to provide structure for the top of an application while in fullscreen mode. - fileName: fullscreen-bar-no-children.tsx - title: Fullscreen bar no children + title: No children description: Use this default to show ONLY the Back button. --- diff --git a/polaris.shopify.com/content/components/grid.md b/polaris.shopify.com/content/components/grid.md index 4b1615cff02..648d4b85d3c 100644 --- a/polaris.shopify.com/content/components/grid.md +++ b/polaris.shopify.com/content/components/grid.md @@ -17,21 +17,17 @@ status: message: This component is in development. There could be breaking changes made to it in a non-major release of Polaris. Please use with caution. examples: - fileName: grid-two-column.tsx - title: Two column wrapping layout - description: >- - Use to create a two column layout that wraps at a breakpoint and aligns to a twelve column grid. - - fileName: grid-two-third-one-third.tsx - title: Two-thirds column one-third column wrapping layout - description: >- - Use to create a two-thirds, one-third column layout that wraps at a breakpoint and aligns to a twelve column grid. - - fileName: grid-three-thirds.tsx - title: Three one-third column wrapping layout with a custom column count - description: >- - Use to create a three column layout that wrap at a breakpoint and aligns to a twelve column grid. + title: Two column + description: Use to create a two column layout that wraps at a breakpoint and aligns to a twelve column grid. + - fileName: grid-two-thirds-and-one-third-column.tsx + title: Two-thirds and one-third column + description: Use to create a two-thirds, one-third column layout that wraps at a breakpoint and aligns to a twelve column grid. + - fileName: grid-three-one-third-column.tsx + title: Three one-third column + description: Use to create a three column layout that wrap at a breakpoint and aligns to a twelve column grid. - fileName: grid-custom-layout.tsx - title: Custom layout using grid areas and custom columns - description: >- - Use to create a layout that can be customized at specific breakpoints. + title: Custom layout + description: Use to create a layout that can be customized at specific breakpoints. --- # Grid diff --git a/polaris.shopify.com/content/components/heading.md b/polaris.shopify.com/content/components/heading.md index 48f9eec07a4..afe45a06f40 100644 --- a/polaris.shopify.com/content/components/heading.md +++ b/polaris.shopify.com/content/components/heading.md @@ -14,8 +14,8 @@ keywords: - heading text - heading font examples: - - fileName: heading-typographic.tsx - title: Typographic heading + - fileName: heading-default.tsx + title: Default description: Use for the title of each top-level page section. --- diff --git a/polaris.shopify.com/content/components/icon.md b/polaris.shopify.com/content/components/icon.md index ade72a03d79..9c7bdc48504 100644 --- a/polaris.shopify.com/content/components/icon.md +++ b/polaris.shopify.com/content/components/icon.md @@ -15,26 +15,20 @@ keywords: - alert examples: - fileName: icon-default.tsx - title: Default icon - description: >- - Use to visually communicate core parts of the product and available - actions. + title: Default + description: Use to visually communicate core parts of the product and available actions. - fileName: icon-colored.tsx - title: Colored icon + title: Colored description: Apply a color to the icon. - fileName: icon-with-backdrop.tsx - title: Icon with backdrop + title: With backdrop description: Apply a backdrop to the icon. - - fileName: icon-user-provided.tsx - title: User provided icon - description: >- - Specify an SVG as a string to render it in an image tag, instead of an - inline SVG to prevent script injection. - - fileName: icon-user-provided-with-color-and-current-color.tsx - title: User provided icon with color and currentColor - description: >- - When using changing color of an svg and it uses currentColor, the white - color is applied. + - fileName: icon-with-custom-svg.tsx + title: With custom SVG + description: Specify an SVG as a string to render it in an image tag, instead of an inline SVG to prevent script injection. + - fileName: icon-with-custom-svg-and-color.tsx + title: With custom SVG and color + description: When using changing color of an svg and it uses currentColor, the white color is applied. --- # Icon diff --git a/polaris.shopify.com/content/components/index-table.md b/polaris.shopify.com/content/components/index-table.md index 3a01afd1eea..dbef8ddded9 100644 --- a/polaris.shopify.com/content/components/index-table.md +++ b/polaris.shopify.com/content/components/index-table.md @@ -27,64 +27,54 @@ keywords: - filter - sort examples: - - fileName: index-table-simple.tsx - title: Simple index table - description: >- - A index table with simple items and no bulk actions, sorting, or - filtering. - - fileName: index-table-simple-small-screen.tsx - title: Simple small screen index table - description: >- - A small screen index table with simple items and no bulk actions, sorting, - or filtering. + - fileName: index-table-default.tsx + title: Default + description: A index table with simple items and no bulk actions, sorting, or filtering. + - fileName: index-table-flush.tsx + title: Flush + description: A index table with simple items and no bulk actions, sorting, or filtering. + - fileName: index-table-small-screen.tsx + title: Small screen + description: A small screen index table with simple items and no bulk actions, sorting, or filtering. - fileName: index-table-with-empty-state.tsx - title: IndexTable with empty state - description: >- - Use to explain the purpose of a index table when no resources exist yet. - This allows a smooth transition from a list in a loading state to a list - where zero, one, or many resources exist. + title: With empty state + description: Use to explain the purpose of a index table when no resources exist yet. This allows a smooth transition from a list in a loading state to a list where zero, one, or many resources exist. - fileName: index-table-with-bulk-actions.tsx - title: IndexTable with bulk actions + title: With bulk actions description: Allows merchants to select items and perform an action on the selection. - fileName: index-table-with-multiple-promoted-bulk-actions.tsx - title: IndexTable with multiple promoted bulk actions - description: >- - Allows merchants to select items and perform different actions on the - selection. + title: With multiple promoted bulk actions + description: Allows merchants to select items and perform different actions on the selection. - fileName: index-table-with-bulk-actions-and-selection-across-pages.tsx - title: IndexTable with bulk actions and selection across pages - description: >- - Allows merchants to select items, perform an action on the selection and - select resources across pages. + title: With bulk actions and selection across pages + description: Allows merchants to select items, perform an action on the selection and select resources across pages. - fileName: index-table-with-loading-state.tsx - title: IndexTable with loading state + title: With loading state description: Notifies merchants that index table items are being processed. - fileName: index-table-with-filtering.tsx - title: IndexTable with filtering - description: >- - Allows merchants to narrow the index table to a subset of the original - items. + title: With filtering + description: Allows merchants to narrow the index table to a subset of the original items. - fileName: index-table-with-row-status.tsx - title: Index table with row status + title: With row status description: An index table with rows differentiated by status. - fileName: index-table-with-sticky-last-column.tsx - title: Index table with sticky last column - description: >- - An index table with a sticky last column that stays visible on scroll. The - last heading will also be sticky if not hidden. + title: With sticky last column + description: An index table with a sticky last column that stays visible on scroll. The last heading will also be sticky if not hidden. + - fileName: index-table-with-row-navigation-link.tsx + title: With row navigation link + description: Use when clicking the row should navigate merchants to another page, like the row item's detail page. When a row contains a `Link` with the `dataPrimaryLink` prop set to `true`, clicking the row will trigger navigation to the link's `url` instead of selecting the row as well as trigger the callback set on the `IndexTable` `onNavigation` prop if provided. + - fileName: index-table-with-clickable-button-column.tsx + title: With clickable button column + description: Use when clicking the row should navigate merchants to another page, like the row item's detail page. When a row contains a `Button` with the `dataPrimaryLink` prop set to `true`, clicking the row will navigate to the `Button` `url` if set instead of selecting the row as well as trigger the callback set on the `IndexTable` `onNavigation` prop if provided. - fileName: index-table-without-checkboxes.tsx - title: Index table without checkboxes + title: Without checkboxes description: An index table without checkboxes and bulk actions. - fileName: index-table-with-all-of-its-elements.tsx - title: IndexTable with all of its elements - description: >- - Use as a broad example that includes most of the elements and props - available to index table. + title: With all of its elements + description: Use as a broad example that includes most of the elements and props available to index table. - fileName: index-table-small-screen-with-all-of-its-elements.tsx - title: Small screen IndexTable with all of its elements - description: >- - Use as a broad example that includes most of the elements and props - available to index table. + title: Small screen with all of its elements + description: Use as a broad example that includes most of the elements and props available to index table. --- # Index table @@ -196,13 +186,14 @@ An `IndexTableRow` is used to render a row representing an item within an `Index ### IndexTableRow properties -| Prop | Type | Description | -| -------- | --------- | --------------------------------------------------------------- | -| id | string | A unique identifier for the row | -| selected | boolean | A boolean property indicating whether the row is selected | -| position | number | The index position of the row | -| subdued | boolean | A boolean property indicating whether the row should be subdued | -| status | RowStatus | A property indicating whether the row should have a status | +| Prop | Type | Description | +| -------- | ---------- | --------------------------------------------------------------- | +| id | string | A unique identifier for the row | +| selected | boolean | A boolean property indicating whether the row is selected | +| position | number | The index position of the row | +| subdued | boolean | A boolean property indicating whether the row should be subdued | +| status | RowStatus | A property indicating whether the row should have a status | +| onClick | () => void | A function which overrides the default click behaviour | ## IndexTableCell @@ -210,9 +201,10 @@ An `IndexTableCell` is used to render a single cell within an `IndexTableRow` ### IndexTableCell properties -| Prop | Type | Description | -| ----- | ------- | -------------------------------------------------------------------------------- | -| flush | boolean | A boolean property indicating whether the cell should remove the default padding | +| Prop | Type | Description | +| --------- | ------- | -------------------------------------------------------------------------------- | +| flush | boolean | A boolean property indicating whether the cell should remove the default padding | +| className | string | Adds a class to the cell, used for setting widths of a cell | --- diff --git a/polaris.shopify.com/content/components/inline-error.md b/polaris.shopify.com/content/components/inline-error.md index b5f58457040..52d04044a89 100644 --- a/polaris.shopify.com/content/components/inline-error.md +++ b/polaris.shopify.com/content/components/inline-error.md @@ -8,12 +8,9 @@ keywords: - invalid input - form group examples: - - fileName: inline-error-basic.tsx - title: Basic inline error - description: >- - Use when the merchant has entered information that is not valid into - multiple fields inside of a form, or needs to be displayed in a - non-standard position in the form layout. + - fileName: inline-error-default.tsx + title: Default + description: Use when the merchant has entered information that is not valid into multiple fields inside of a form, or needs to be displayed in a non-standard position in the form layout. --- # Inline error diff --git a/polaris.shopify.com/content/components/keyboard-key.md b/polaris.shopify.com/content/components/keyboard-key.md index 2390fa79d41..b6060b46426 100644 --- a/polaris.shopify.com/content/components/keyboard-key.md +++ b/polaris.shopify.com/content/components/keyboard-key.md @@ -11,7 +11,7 @@ keywords: - hotkey combinations examples: - fileName: keyboard-key-default.tsx - title: List of keyboard shortcuts + title: Default description: Use to list a related set of keyboard shortcuts. --- diff --git a/polaris.shopify.com/content/components/layout.md b/polaris.shopify.com/content/components/layout.md index 8baa904811e..ac76c70c05e 100644 --- a/polaris.shopify.com/content/components/layout.md +++ b/polaris.shopify.com/content/components/layout.md @@ -17,35 +17,25 @@ keywords: - annotated sections examples: - fileName: layout-one-column.tsx - title: One-column layout - description: >- - Use to have a single section on its own in a full-width container. Use for - simple pages and as a container for banners and other full-width content. + title: One-column + description: Use to have a single section on its own in a full-width container. Use for simple pages and as a container for banners and other full-width content. - fileName: layout-two-columns-with-primary-and-secondary-widths.tsx title: Two columns with primary and secondary widths - description: >- - Use to follow a normal section with a secondary section to create a 2/3 + - 1/3 layout on detail pages (such as individual product or order pages). - Can also be used on any page that needs to structure a lot of content. - This layout stacks the columns on small screens. + description: Use to follow a normal section with a secondary section to create a 2/3 + 1/3 layout on detail pages (such as individual product or order pages). Can also be used on any page that needs to structure a lot of content. This layout stacks the columns on small screens. - fileName: layout-two-columns-with-equal-width.tsx title: Two columns with equal width - description: >- - Use to create a ½ + ½ layout. Can be used to display content of equal - importance. This layout will stack the columns on small screens. + description: Use to create a ½ + ½ layout. Can be used to display content of equal importance. This layout will stack the columns on small screens. - fileName: layout-three-columns-with-equal-width.tsx title: Three columns with equal width - description: >- - Use to create a ⅓ + ⅓ + ⅓ layout. Can be used to display content of equal - importance. This layout will stack the columns on small screens. + description: Use to create a ⅓ + ⅓ + ⅓ layout. Can be used to display content of equal importance. This layout will stack the columns on small screens. - fileName: layout-annotated.tsx - title: Annotated layout - description: >- - Use for settings pages. When settings are grouped thematically in - annotated sections, the title and description on each section helps - merchants quickly find the setting they’re looking for. + title: Annotated + description: Use for settings pages. When settings are grouped thematically in annotated sections, the title and description on each section helps merchants quickly find the setting they’re looking for. + - fileName: layout-annotated-with-sections.tsx + title: Annotated with sections + description: Use for settings pages. When settings are grouped thematically in annotated sections, the title and description on each section helps merchants quickly find the setting they’re looking for. - fileName: layout-annotated-with-banner-at-the-top.tsx - title: Annotated layout with Banner at the top + title: Annotated with Banner at the top description: Use for settings pages that need a banner or other content at the top. --- diff --git a/polaris.shopify.com/content/components/link.md b/polaris.shopify.com/content/components/link.md index 54327fb5c28..328f18e1bba 100644 --- a/polaris.shopify.com/content/components/link.md +++ b/polaris.shopify.com/content/components/link.md @@ -20,20 +20,18 @@ keywords: - secondary cta - secondary call to action examples: - - fileName: link-defaults.tsx - title: Default links + - fileName: link-default.tsx + title: Default description: Use for text links in larger spans of text. - fileName: link-monochrome.tsx - title: Monochrome link + title: Monochrome description: Use for text links that are the same color as the surrounding text. - fileName: link-monochrome-in-a-banner.tsx - title: Monochrome link in a banner + title: Monochrome in a banner + description: Monochrome styles will be applied to links rendered within a `Banner`. - fileName: link-external.tsx - title: External link - description: >- - Use for text links that should open in a new browser tab (or window, - depending on the merchant’s browser settings). Use this only when opening - a page in the same tab might disrupt the merchant’s workflow. + title: External + description: Use for text links that should open in a new browser tab (or window, depending on the merchant’s browser settings). Use this only when opening a page in the same tab might disrupt the merchant’s workflow. --- # Link diff --git a/polaris.shopify.com/content/components/list.md b/polaris.shopify.com/content/components/list.md index ac68d82e300..396d83bdb64 100644 --- a/polaris.shopify.com/content/components/list.md +++ b/polaris.shopify.com/content/components/list.md @@ -10,16 +10,11 @@ keywords: - text-only lists examples: - fileName: list-bulleted.tsx - title: Bulleted list - description: >- - Use for a text-only list of related items that don’t need to be in a - specific order and don’t require an icon or other - indicator. + title: Bulleted + description: Use for a text-only list of related items that don’t need to be in a specific order and don’t require an icon or other indicator. - fileName: list-numbered.tsx - title: Numbered list - description: >- - Use for a text-only list of related items when an inherent order, - priority, or sequence needs to be communicated. + title: Numbered + description: Use for a text-only list of related items when an inherent order, priority, or sequence needs to be communicated. --- # List diff --git a/polaris.shopify.com/content/components/listbox.md b/polaris.shopify.com/content/components/listbox.md index 81a817a848c..7ba1b2d2c54 100644 --- a/polaris.shopify.com/content/components/listbox.md +++ b/polaris.shopify.com/content/components/listbox.md @@ -7,21 +7,17 @@ keywords: - list box - interactive list examples: - - fileName: listbox-basic.tsx - title: Basic Listbox - description: >- - Basic implementation of a control element used to let merchants select - options + - fileName: listbox-default.tsx + title: Default + description: Basic implementation of a control element used to let merchants select options - fileName: listbox-with-loading.tsx - title: Listbox with Loading - description: >- - Implementation of a control element showing a loading indicator to let - merchants know more options are being loaded + title: With Loading + description: Implementation of a control element showing a loading indicator to let merchants know more options are being loaded - fileName: listbox-with-action.tsx - title: Listbox with Action + title: With Action description: Implementation of a control element used to let merchants take an action - fileName: listbox-with-custom-element.tsx - title: Listbox with custom element + title: With custom element description: Implementation of a control with custom rendering of options --- diff --git a/polaris.shopify.com/content/components/loading.md b/polaris.shopify.com/content/components/loading.md index 80edeca2b16..23523cc3fb3 100644 --- a/polaris.shopify.com/content/components/loading.md +++ b/polaris.shopify.com/content/components/loading.md @@ -8,7 +8,7 @@ keywords: - loading bar examples: - fileName: loading-default.tsx - title: Default loading + title: Default description: Use to indicate that the page is loading. --- diff --git a/polaris.shopify.com/content/components/media-card.md b/polaris.shopify.com/content/components/media-card.md index 38cf9c7a885..9b05bfaf337 100644 --- a/polaris.shopify.com/content/components/media-card.md +++ b/polaris.shopify.com/content/components/media-card.md @@ -12,32 +12,24 @@ keywords: - card with thumbnail - thumbnail card examples: - - fileName: media-card-basic.tsx - title: Basic media card + - fileName: media-card-default.tsx + title: Default description: Use to surface educational information about a feature or opportunity. - - fileName: media-card-basic-with-small-visual.tsx - title: Basic media card with small visual - description: >- - Use when there are limited vertical space, or when the card should be less - prominent. + - fileName: media-card-with-small-visual.tsx + title: With small visual + description: Use when there are limited vertical space, or when the card should be less prominent. - fileName: media-card-with-secondary-action.tsx - title: Media card with secondary action - description: >- - Use when there are two distinct actions merchants can take on the - information in the card. + title: With secondary action + description: Use when there are two distinct actions merchants can take on the information in the card. - fileName: media-card-with-no-actions.tsx - title: Media card with no actions + title: With no actions description: Use when media card does not require any actions. - fileName: media-card-video-card.tsx title: Video card - description: >- - Use to provide a consistent layout for contextual learning content. Use to - wrap thumbnails of educational videos about Shopify features in context. + description: Use to provide a consistent layout for contextual learning content. Use to wrap thumbnails of educational videos about Shopify features in context. - fileName: media-card-portrait-video-card.tsx title: Portrait video card - description: >- - Use when vertical screen space is not limited or when the video card is - the page’s primary content. For example, in an empty state. + description: Use when vertical screen space is not limited or when the video card is the page’s primary content. For example, in an empty state. --- # Media card diff --git a/polaris.shopify.com/content/components/modal.md b/polaris.shopify.com/content/components/modal.md index 0e49b2698e2..6f5c024d83c 100644 --- a/polaris.shopify.com/content/components/modal.md +++ b/polaris.shopify.com/content/components/modal.md @@ -25,33 +25,33 @@ keywords: - dialog - alert examples: - - fileName: modal-basic.tsx - title: Basic modal + - fileName: modal-default.tsx + title: Default description: Use as the default option for a modal. - fileName: modal-with-primary-action.tsx - title: Modal with primary action + title: With primary action description: Use to let merchants take a key action. - fileName: modal-with-primary-and-secondary-actions.tsx - title: Modal with primary and secondary actions - description: >- - Use to let merchants take key actions at the bottom of the - modal. + title: With primary and secondary actions + description: Use to let merchants take key actions at the bottom of the modal. - fileName: modal-large.tsx - title: Large modal + title: Large description: Use when you need to increase the width of your modal. - fileName: modal-small.tsx - title: Small modal + title: Small description: Use when you need to decrease the width of your modal. - fileName: modal-without-a-title.tsx - title: Modal without a title + title: Without a title description: A title is required for accessibility, but you may hide it. - fileName: modal-with-scroll-listener.tsx - title: Modal with scroll listener + title: With scroll listener description: Use to implement infinite scroll of modal content. - fileName: modal-with-activator-ref.tsx - title: Modal with activator ref + title: With activator ref + description: Provide an activator ref when it’s more convenient than providing an element. This ensures proper focus management when closing the modal. See the [accessibility features of a modal](https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html) for more information regarding focus. - fileName: modal-without-an-activator-prop.tsx - title: Modal without an activator prop + title: Without an activator prop + description: Use an external activator when technical limitations prevent you from passing the activator as an element or a ref. Make sure to focus the activator on close when choosing this approach. See the [accessibility features of a modal](https://www.w3.org/TR/wai-aria-practices/examples/dialog-modal/dialog.html) for more information regarding focus. --- # Modal diff --git a/polaris.shopify.com/content/components/navigation.md b/polaris.shopify.com/content/components/navigation.md index 0f6dca31d48..fbafc8e3d78 100644 --- a/polaris.shopify.com/content/components/navigation.md +++ b/polaris.shopify.com/content/components/navigation.md @@ -11,48 +11,36 @@ keywords: - sidebar - side bar examples: - - fileName: navigation-basic.tsx - title: Basic navigation + - fileName: navigation-default.tsx + title: Default + description: Use to present a navigation menu in the [frame](https://polaris.shopify.com/components/frame). - fileName: navigation-with-multiple-secondary-navigations.tsx - title: Navigation with multiple secondary navigations - description: >- - Use to present a secondary action, related to a section and to title the - section. - - fileName: navigation-with-an-active-root-item-with-secondary-items.tsx - title: Navigation with an active root item with secondary navigation items - description: >- - Use to present a secondary action, related to a section and to title the - section. + title: With multiple secondary navigations + description: Use to present a secondary action, related to a section and to title the section. + - fileName: navigation-with-an-active-root-item-with-secondary-navigation-items.tsx + title: With an active root item with secondary navigation items + description: Use to present a secondary action, related to a section and to title the section. - fileName: navigation-with-a-secondary-action-for-a-section-and-a-section-title.tsx - title: Navigation with a secondary action for a section and a section title - description: >- - Use to present a secondary action, related to a section and to title the - section. + title: With a secondary action for a section and a section title + description: Use to present a secondary action, related to a section and to title the section. - fileName: navigation-with-a-secondary-action-for-an-item.tsx - title: Navigation with a secondary action for an item - description: >- - Use to add a different action for an item than the main action, like to - view or add something. + title: With a secondary action for an item + description: Use to add a different action for an item than the main action, like to view or add something. - fileName: navigation-with-section-rollup.tsx - title: Navigation with section rollup - description: >- - Use to show a limited number of items in a section with an option to - expand the remaining items. + title: With section rollup + description: Use to show a limited number of items in a section with an option to expand the remaining items. - fileName: navigation-with-section-separator.tsx - title: Navigation with section separator + title: With section separator description: Use to add a horizontal line below the section. - fileName: navigation-with-various-states-and-secondary-elements.tsx - title: Navigation with various states and secondary elements - description: >- - This example showcases the many elements that can compose a navigation, - especially useful for testing purposes. + title: With various states and secondary elements + description: This example showcases the many elements that can compose a navigation, especially useful for testing purposes. - fileName: navigation-with-aria-labelledby.tsx - title: Navigation with aria-labelledby + title: With aria-labelledby + description: This example shows how to add an aria-labelledby to add a hidden label to the `nav` element. - fileName: navigation-using-major-icons.tsx - title: Navigation using Major icons - description: >- - This example shows how to use the shouldResizeIcon prop when using Major - icons + title: Using Major icons + description: This example shows how to use the shouldResizeIcon prop when using Major icons --- # Navigation diff --git a/polaris.shopify.com/content/components/option-list.md b/polaris.shopify.com/content/components/option-list.md index d3625b5559b..2991732d62d 100644 --- a/polaris.shopify.com/content/components/option-list.md +++ b/polaris.shopify.com/content/components/option-list.md @@ -12,21 +12,17 @@ keywords: - collection lists - list selection examples: - - fileName: option-list-simple.tsx - title: Simple option list - description: >- - Use for a group of similar selectable items when only one should be - selectable at once. + - fileName: option-list-default.tsx + title: Default + description: Use for a group of similar selectable items when only one should be selectable at once. - fileName: option-list-multiple.tsx - title: Multiple option list - description: >- - Use when you have a group of similar selectable items and more than one - item can be selected at once. + title: Multiple + description: Use when you have a group of similar selectable items and more than one item can be selected at once. - fileName: option-list-with-sections.tsx - title: Option list with sections + title: With sections description: Use sections when you have multiple groups of similar selectable items. - fileName: option-list-in-a-popover.tsx - title: Option list in a popover + title: In a popover description: Use when a set of selections won’t fit in the available screen space. --- diff --git a/polaris.shopify.com/content/components/page-actions.md b/polaris.shopify.com/content/components/page-actions.md index afdb9ffcee6..75f58696830 100644 --- a/polaris.shopify.com/content/components/page-actions.md +++ b/polaris.shopify.com/content/components/page-actions.md @@ -13,16 +13,16 @@ keywords: - delete actions examples: - fileName: page-actions-default.tsx - title: Default page actions - description: >- - Used on a resource page (such as an individual order or product page) to - let merchants take key actions at the bottom of the page. Usually, the - primary action is Save and the secondary action is Delete. + title: Default + description: Used on a resource page (such as an individual order or product page) to let merchants take key actions at the bottom of the page. Usually, the primary action is Save and the secondary action is Delete. - fileName: page-actions-primary-action-only.tsx title: Primary action only description: Not all page actions require a secondary action. + - fileName: page-actions-with-custom-primary-action.tsx + title: With custom primary action + description: Use to create a custom primary action. - fileName: page-actions-with-custom-secondary-action.tsx - title: Page actions with custom secondary action + title: With custom secondary action description: Use to create a custom secondary action. --- diff --git a/polaris.shopify.com/content/components/page.md b/polaris.shopify.com/content/components/page.md index 5c26424a6d0..89df78bed6b 100644 --- a/polaris.shopify.com/content/components/page.md +++ b/polaris.shopify.com/content/components/page.md @@ -19,72 +19,45 @@ keywords: - page actions - page layouts examples: - - fileName: page-with-all-header-elements.tsx - title: Page with all header elements - description: >- - Use for detail pages, which should have pagination and breadcrumbs, and - also often have several actions.Use for detail pages, which should have - breadcrumbs, and also often have several actions.Use for building any page - on Android. Use for detail pages, which should have breadcrumbs, - and also often have several actions.Use for building any page on - iOS. + - fileName: page-default.tsx + title: Default + description: Use for detail pages, which should have pagination and breadcrumbs, and also often have several actions. - fileName: page-with-custom-primary-action.tsx - title: Page with custom primary action + title: With custom primary action description: Use to create a custom primary action. - fileName: page-without-primary-action-in-header.tsx - title: Page without primary action in header - description: >- - Use when a primary action functions better as part of the page content - instead of in the page header. + title: Without primary action in header + description: Use when a primary action functions better as part of the page content instead of in the page header. - fileName: page-with-destructive-secondary-action.tsx - title: Page with destructive secondary action + title: With destructive secondary action description: Used to visually indicate that the secondary page action is destructive. - fileName: page-with-custom-secondary-action.tsx - title: Page with custom secondary action + title: With custom secondary action description: Use to create a custom secondary action. - fileName: page-with-subtitle.tsx - title: Page with subtitle + title: With subtitle description: Use when the page title benefits from secondary content. - fileName: page-with-external-link.tsx - title: Page with external link - description: >- - Use when a secondary action links to another website. Actions marked - external open in a new browser tab. + title: With external link + description: Use when a secondary action links to another website. Actions marked external open in a new browser tab. - fileName: page-without-pagination.tsx - title: Page without pagination - description: >- - Use when the page doesn’t represent a list of objects or a detail view for - an object. + title: Without pagination + description: Use when the page doesn’t represent a list of objects or a detail view for an object. - fileName: page-full-width.tsx - title: Full-width page - description: >- - Use for layouts that benefit from more screen width, such as wide tables - or lists. + title: Full-width + description: Use for layouts that benefit from more screen width, such as wide tables or lists. - fileName: page-narrow-width.tsx - title: Narrow width page - description: >- - Use a narrow width layout if the page supports a single unified task. When - merchants must review the entire page contents to complete their goal, - this layout helps focus their attention in a single path from top to - bottom. + title: Narrow width + description: Use a narrow width layout if the page supports a single unified task. When merchants must review the entire page contents to complete their goal, this layout helps focus their attention in a single path from top to bottom. - fileName: page-with-action-groups.tsx - title: Page with action groups - description: >- - Use action groups for sets of actions that relate to one another, - particularly when there are too many to display as secondary actions. Note - that these groups will be further rolled up into a single action for - smaller displays so that actions do not wrap or overflow the page bounds. - - fileName: page-with-content-after-title-title-metadata.tsx - title: Page with content after title (title metadata) - description: >- - Title metadata appears immediately after the page’s title. Use it to - communicate brief, important and non-interactive status information about - an entire page. + title: With action groups + description: Use action groups for sets of actions that relate to one another, particularly when there are too many to display as secondary actions. Note that these groups will be further rolled up into a single action for smaller displays so that actions do not wrap or overflow the page bounds. + - fileName: page-with-content-after-title.tsx + title: With content after title + description: Title metadata appears immediately after the page’s title. Use it to communicate brief, important and non-interactive status information about an entire page. - fileName: page-with-divider.tsx - title: Page with divider - description: >- - Use when the page needs visual separation between the page header and the - content. + title: With divider + description: Use when the page needs visual separation between the page header and the content. --- # Page diff --git a/polaris.shopify.com/content/components/pagination.md b/polaris.shopify.com/content/components/pagination.md index ecd11995029..3ea7cc6bce4 100644 --- a/polaris.shopify.com/content/components/pagination.md +++ b/polaris.shopify.com/content/components/pagination.md @@ -20,16 +20,14 @@ keywords: - next buttons examples: - fileName: pagination-default.tsx - title: Default pagination + title: Default description: Use for pagination at the bottom of lists. - fileName: pagination-with-keyboard-navigation.tsx - title: Pagination with keyboard navigation + title: With keyboard navigation description: Attach standard keyboard shortcuts to important pagination controls. - fileName: pagination-with-label.tsx - title: Pagination with label - description: >- - Add a label between navigation buttons to provide more context of the - content being viewed by the user. + title: With label + description: Add a label between navigation buttons to provide more context of the content being viewed by the user. --- # Pagination diff --git a/polaris.shopify.com/content/components/popover.md b/polaris.shopify.com/content/components/popover.md index 529288244da..f034be1b21d 100644 --- a/polaris.shopify.com/content/components/popover.md +++ b/polaris.shopify.com/content/components/popover.md @@ -21,25 +21,17 @@ keywords: - action sheet examples: - fileName: popover-with-action-list.tsx - title: Popover with action list - description: >- - Use when presenting a set of actions in a disclosable - menu. + title: With action list + description: Use when presenting a set of actions in a disclosable menu. - fileName: popover-with-content-and-actions.tsx - title: Popover with content and actions - description: >- - Use to present a combination of content, instructions, and actions in a - panel for tasks that are of low or secondary importance to the current - page. When used this way, popovers provide useful entry points to related - features without overwhelming merchants. + title: With content and actions + description: Use to present a combination of content, instructions, and actions in a panel for tasks that are of low or secondary importance to the current page. When used this way, popovers provide useful entry points to related features without overwhelming merchants. - fileName: popover-with-form-components.tsx - title: Popover with form components + title: With form components description: Use to present secondary input tasks on demand. - fileName: popover-with-lazy-loaded-list.tsx - title: Popover with lazy loaded list - description: >- - Use to present merchants with a list that dynamically loads more items on - scroll or arrow down. + title: With lazy loaded list + description: Use to present merchants with a list that dynamically loads more items on scroll or arrow down. --- # Popover diff --git a/polaris.shopify.com/content/components/progress-bar.md b/polaris.shopify.com/content/components/progress-bar.md index e989358d425..618918dd536 100644 --- a/polaris.shopify.com/content/components/progress-bar.md +++ b/polaris.shopify.com/content/components/progress-bar.md @@ -10,22 +10,15 @@ keywords: examples: - fileName: progress-bar-default.tsx title: Default - description: >- - Use this component to visually represent the completion of a task or - operation. + description: Use this component to visually represent the completion of a task or operation. - fileName: progress-bar-small.tsx - title: Small progress bar - description: >- - Use the size option when you need to increase or decrease the visual - weight of the progress bar. + title: Small + description: Use the size option when you need to increase or decrease the visual weight of the progress bar. - fileName: progress-bar-colored.tsx - title: Colored progress bars - description: >- - Use the color option when you need to blend the progress bar in a context - that calls for it, such as a progress toward success or where it’s the - primary focus. + title: Colored + description: Use the color option when you need to blend the progress bar in a context that calls for it, such as a progress toward success or where it’s the primary focus. - fileName: progress-bar-non-animated.tsx - title: Non-animated progress bar + title: Non-animated description: Use the animated prop when you want to show a static progress bar. --- diff --git a/polaris.shopify.com/content/components/radio-button.md b/polaris.shopify.com/content/components/radio-button.md index 1aabc532f9a..12511582363 100644 --- a/polaris.shopify.com/content/components/radio-button.md +++ b/polaris.shopify.com/content/components/radio-button.md @@ -15,10 +15,8 @@ keywords: - switch examples: - fileName: radio-button-default.tsx - title: Default radio button - description: >- - Use radio buttons where merchants must make a single - selection. + title: Default + description: Use radio buttons where merchants must make a single selection. --- # Radio button diff --git a/polaris.shopify.com/content/components/range-slider.md b/polaris.shopify.com/content/components/range-slider.md index a1a387367f2..a608b0abe46 100644 --- a/polaris.shopify.com/content/components/range-slider.md +++ b/polaris.shopify.com/content/components/range-slider.md @@ -11,25 +11,19 @@ keywords: - range form examples: - fileName: range-slider-default.tsx - title: Default range slider - description: - - fileName: range-slider-min-and-max-control.tsx - title: Min and max range control - description: >- - Use when a single value needs to be selected from a number range with a - specific minimum and maximum. - - fileName: range-slider-step-incremented-control.tsx - title: Step incremented range control - description: >- - Use when a single value of a specific increment needs to be selected from - a range of numbers. - - fileName: range-slider-prefix-and-suffix-elements.tsx - title: Prefix and suffix elements - description: >- - Use when the start or end of the range input benefits from additional - content. - - fileName: range-slider-dual-thumb.tsx - title: Dual thumb range slider + title: Default + description: Use when a single value between `0 and 100` needs to be selected. + - fileName: range-slider-with-min-and-max.tsx + title: With min and max + description: Use when a single value needs to be selected from a number range with a specific minimum and maximum. + - fileName: range-slider-with-steps.tsx + title: With steps + description: Use when a single value of a specific increment needs to be selected from a range of numbers. + - fileName: range-slider-with-prefix-and-suffix.tsx + title: With prefix and suffix + description: Use when the start or end of the range input benefits from additional content. The height of the range slider component varies based on the presence or absence of props like `label` and `helpText`. Setting a React element on the `prefix` and `suffix` props is supported to enable control of spacing and alignment. + - fileName: range-slider-with-dual-thumb.tsx + title: With dual thumb description: Use when two values need to be selected from a range of numbers. --- diff --git a/polaris.shopify.com/content/components/resource-item.md b/polaris.shopify.com/content/components/resource-item.md index 4b7b29ca55d..73dd0fdf3da 100644 --- a/polaris.shopify.com/content/components/resource-item.md +++ b/polaris.shopify.com/content/components/resource-item.md @@ -23,19 +23,17 @@ keywords: - secondary actions in a list - list of resources examples: - - fileName: resource-item-simple.tsx - title: Simple resource item + - fileName: resource-item-default.tsx + title: Default description: A basic resource item with its details filled in at the point of use. - - fileName: resource-item-item-with-media.tsx - title: Item with media - - fileName: resource-item-item-with-shortcut-actions.tsx - title: Item with shortcut actions - description: >- - Shortcut actions present popular actions from the resource’s details page - for easy access. A shortcut action should be available on every item in - the list. - - fileName: resource-item-item-with-vertical-alignment.tsx - title: Item with vertical alignment + - fileName: resource-item-with-media.tsx + title: With media + description: The media element can hold an [avatar](https://polaris.shopify.com/components/avatar), [thumbnail](https://polaris.shopify.com/components/thumbnail), or other small-format graphic. + - fileName: resource-item-with-shortcut-actions.tsx + title: With shortcut actions + description: Shortcut actions present popular actions from the resource’s details page for easy access. A shortcut action should be available on every item in the list. + - fileName: resource-item-with-vertical-alignment.tsx + title: With vertical alignment description: Use to adjust the vertical alignment of item content. --- diff --git a/polaris.shopify.com/content/components/resource-list.md b/polaris.shopify.com/content/components/resource-list.md index bbcd032e37f..95aa7e4133f 100644 --- a/polaris.shopify.com/content/components/resource-list.md +++ b/polaris.shopify.com/content/components/resource-list.md @@ -24,71 +24,48 @@ keywords: - filter - sort examples: - - fileName: resource-list-simple.tsx - title: Simple resource list - description: >- - A resource list with simple items and no bulk actions, sorting, or - filtering. + - fileName: resource-list-default.tsx + title: Default + description: A resource list with simple items and no bulk actions, sorting, or filtering. - fileName: resource-list-with-empty-state.tsx - title: Resource list with empty state - description: >- - Use to explain the purpose of a list of resources when no resources exist - yet. This allows a smooth transition from a list in a loading state to a - list where zero, one, or many resources exist. + title: With empty state + description: Use to explain the purpose of a list of resources when no resources exist yet. This allows a smooth transition from a list in a loading state to a list where zero, one, or many resources exist. - fileName: resource-list-with-selection-and-no-bulk-actions.tsx - title: Resource list with selection and no bulk actions + title: With selection and no bulk actions description: A resource list with simple items and selection. - fileName: resource-list-with-bulk-actions.tsx - title: Resource list with bulk actions + title: With bulk actions description: Allows merchants to select items and perform an action on the selection. - fileName: resource-list-with-loading-state.tsx - title: Resource list with loading state + title: With loading state description: Notifies merchants that list items are being processed. - fileName: resource-list-with-total-count.tsx - title: Resource list with total resource count - description: >- - Use to indicate that the number of resources shown is a subset of the - total number of resources in the list. + title: With total count + description: Use to indicate that the number of resources shown is a subset of the total number of resources in the list. - fileName: resource-list-with-sorting.tsx - title: Resource list with sorting + title: With sorting + description: Allows merchants to change the way the list is sorted by selecting one of several options from a [Select](https://polaris.shopify.com/components/select) control. - fileName: resource-list-with-alternate-tool.tsx - title: Resource list with alternate tool - description: >- - Allows merchants to add an alternate tool in the current sort option - location when sort may not be the most relevant action for the current - list. + title: With alternate tool + description: Allows merchants to add an alternate tool in the current sort option location when sort may not be the most relevant action for the current list. - fileName: resource-list-with-filtering.tsx - title: Resource list with filtering - description: >- - Allows merchants to narrow the resource list to a subset of the original - items. + title: With filtering + description: Allows merchants to narrow the resource list to a subset of the original items. - fileName: resource-list-with-a-custom-empty-search-result-state.tsx - title: Resource list with a custom empty search result state - description: >- - Allows merchants to narrow the resource list to a subset of the original - items. If the filters or search applied return no results, then display a - custom empty search state. + title: With a custom empty search result state + description: Allows merchants to narrow the resource list to a subset of the original items. If the filters or search applied return no results, then display a custom empty search state. - fileName: resource-list-with-item-shortcut-actions.tsx - title: Resource list with item shortcut actions - description: >- - Shortcut actions are intended to provide quick access to popular actions - from the resource’s details page. They are shown when the mouse is hovered - over the list item, and are not shown on small screen devices, so the - action must also be accessible in another way. + title: With item shortcut actions + description: Shortcut actions are intended to provide quick access to popular actions from the resource’s details page. They are shown when the mouse is hovered over the list item, and are not shown on small screen devices, so the action must also be accessible in another way. - fileName: resource-list-with-persistent-item-shortcut-actions.tsx - title: Resource list with persistent item shortcut actions - description: >- - Use persistent shortcut actions in rare cases when the action cannot be - made available on the item’s details page. Persistent shortcut actions - roll up into an overflow menu on small screens. + title: With persistent item shortcut actions + description: Use persistent shortcut actions in rare cases when the action cannot be made available on the item’s details page. Persistent shortcut actions roll up into an overflow menu on small screens. - fileName: resource-list-with-multiselect.tsx - title: Resource list with multiselect + title: With multiselect description: Allows merchants to select or deselect multiple items at once. - fileName: resource-list-with-all-of-its-elements.tsx - title: Resource list with all of its elements - description: >- - Use as a broad example that includes most props available to resource - list. + title: With all of its elements + description: Use as a broad example that includes most props available to resource list. --- # Resource list diff --git a/polaris.shopify.com/content/components/scrollable.md b/polaris.shopify.com/content/components/scrollable.md index 2afb9729c4b..b8d242f9927 100644 --- a/polaris.shopify.com/content/components/scrollable.md +++ b/polaris.shopify.com/content/components/scrollable.md @@ -14,18 +14,12 @@ keywords: - below the fold - above the fold examples: - - fileName: scrollable-default-container.tsx - title: Default scrollable container - description: >- - Use when you need to make a region within the page independently - scrollable. It’s often used in modals and other panes where it’s helpful - to provide an extra visual cue that content exists below or above the - fold. - - fileName: scrollable-scroll-to-child-component.tsx - title: Scroll to child component - description: >- - Use when you need to programmatically scroll a child component into view - in the scrollable container. + - fileName: scrollable-default.tsx + title: Default + description: Use when you need to make a region within the page independently scrollable. It’s often used in modals and other panes where it’s helpful to provide an extra visual cue that content exists below or above the fold. + - fileName: scrollable-to-child-component.tsx + title: To child component + description: Use when you need to programmatically scroll a child component into view in the scrollable container. --- # Scrollable diff --git a/polaris.shopify.com/content/components/select.md b/polaris.shopify.com/content/components/select.md index 8891f817c7e..e3e8ecb698f 100644 --- a/polaris.shopify.com/content/components/select.md +++ b/polaris.shopify.com/content/components/select.md @@ -21,40 +21,23 @@ keywords: - separate error message examples: - fileName: select-default.tsx - title: Default select - description: >- - Presents a classic dropdown menu or equivalent picker as determined by - merchants’ browsers.The iOS picker expands in-line. Merchants scroll to - select the item they want. The Android menu is similar in behavior - to the web dropdown. + title: Default + description: Presents a classic dropdown menu or equivalent picker as determined by merchants’ browsers. - fileName: select-with-inline-label.tsx - title: Select with inline label - description: >- - Use only for cases where the select must fit on a single line, such as in - a toolbar. + title: With inline label + description: Use only for cases where the select must fit on a single line, such as in a toolbar. - fileName: select-disabled.tsx - title: Disabled select - description: >- - Use for selections that aren’t currently available. The surrounding - interface should make it clear why the select box is disabled and how to - activate it. + title: Disabled + description: Use for selections that aren’t currently available. The surrounding interface should make it clear why the select box is disabled and how to activate it. - fileName: select-with-prefix.tsx - title: Select with prefix - description: >- - Renders any React element to the left of individual select options. Does - not show in the dropdown. + title: With prefix + description: Renders any React element to the left of individual select options. Does not show in the dropdown. - fileName: select-with-validation-error.tsx - title: Select with validation error - description: >- - Use to let merchants know if there’s a problem with their selection. For - selects, a selection is typically invalid only when using a placeholder - option (“Select”) and no other selection has been made. + title: With validation error + description: Use to let merchants know if there’s a problem with their selection. For selects, a selection is typically invalid only when using a placeholder option (“Select”) and no other selection has been made. - fileName: select-with-separate-validation-error.tsx - title: Select with separate validation error - description: >- - Use to let merchants know when their select input is invalid in the - context of a group of form inputs that the select depends on.To render an - invalid select and its validation error separately: + title: With separate validation error + description: Use to let merchants know when their select input is invalid in the context of a group of form inputs that the select depends on. --- # Select diff --git a/polaris.shopify.com/content/components/setting-toggle.md b/polaris.shopify.com/content/components/setting-toggle.md index fbcb78c8035..0e8499908ab 100644 --- a/polaris.shopify.com/content/components/setting-toggle.md +++ b/polaris.shopify.com/content/components/setting-toggle.md @@ -16,10 +16,8 @@ keywords: - adjuster examples: - fileName: setting-toggle-default.tsx - title: Default setting toggle - description: >- - Use on settings pages to allow merchants to toggle a setting that has an - activated or a deactivated state. + title: Default + description: Use on settings pages to allow merchants to toggle a setting that has an activated or a deactivated state. --- # Setting toggle @@ -45,13 +43,11 @@ Settings toggles should: Toggle descriptions should: - Clearly indicate whether the setting is activated or deactivated -- Explain the implications of the state of the setting to merchants - (“Automatic messages are deactivated. Your customers won’t receive automatic shipping updates.”) +- Explain the implications of the state of the setting to merchants (“Automatic messages are deactivated. Your customers won’t receive automatic shipping updates.”) ### Primary button -The primary buttons for the setting toggle should always say either “Activate” or -“Deactivate” depending on whether the setting can be turned on or off. +The primary buttons for the setting toggle should always say either “Activate” or “Deactivate” depending on whether the setting can be turned on or off. For example, if the setting toggle is on, the button should say “Deactivate” to allow merchants to turn it off. If the setting toggle is off, the button should say “Activate” to allow merchants to turn it on. diff --git a/polaris.shopify.com/content/components/sheet.md b/polaris.shopify.com/content/components/sheet.md index f1e39984239..b5532309bc2 100644 --- a/polaris.shopify.com/content/components/sheet.md +++ b/polaris.shopify.com/content/components/sheet.md @@ -13,8 +13,8 @@ status: value: Deprecated message: The sheet component encourages designers to create a new layer on top of the page instead of improving the existing user interface. It also blocks other parts of the UI, forces users to switch context, and adds complexity to otherwise simple interactions. examples: - - fileName: sheet-basic.tsx - title: Basic sheet + - fileName: sheet-default.tsx + title: Default description: Use as the default option for a sheet. --- diff --git a/polaris.shopify.com/content/components/skeleton-body-text.md b/polaris.shopify.com/content/components/skeleton-body-text.md index aa5559c194b..29cd9539e2c 100644 --- a/polaris.shopify.com/content/components/skeleton-body-text.md +++ b/polaris.shopify.com/content/components/skeleton-body-text.md @@ -8,17 +8,12 @@ keywords: - loading - page examples: - - fileName: skeleton-body-text-default-paragraph.tsx - title: Default paragraph - description: >- - Use this component to represent a block of content being loaded. For - example, you could use it to represent an entire product description card - on the product page. + - fileName: skeleton-body-text-default.tsx + title: Default + description: Use this component to represent a block of content being loaded. For example, you could use it to represent an entire product description card on the product page. - fileName: skeleton-body-text-single-line-content.tsx title: Single line content - description: >- - Use this component to represent a short, single line of text, like a - timestamp. + description: Use this component to represent a short, single line of text, like a timestamp. --- # Skeleton body text diff --git a/polaris.shopify.com/content/components/skeleton-display-text.md b/polaris.shopify.com/content/components/skeleton-display-text.md index 2e150f84311..fa773ea6fcd 100644 --- a/polaris.shopify.com/content/components/skeleton-display-text.md +++ b/polaris.shopify.com/content/components/skeleton-display-text.md @@ -8,19 +8,15 @@ keywords: - loading - page examples: - - fileName: skeleton-display-text-medium-and-large-display-text.tsx - title: Medium and large display text - description: >- - Use this component to represent medium and large display text such as - large metrics on the reports list page, or for page titles. - - fileName: skeleton-display-text-extra-large-display-text.tsx - title: Extra large display text + - fileName: skeleton-display-text-medium-and-large.tsx + title: Medium and large + description: Use this component to represent medium and large display text such as large metrics on the reports list page, or for page titles. + - fileName: skeleton-display-text-extra-large.tsx + title: Extra large description: Use this component to represent extra large display text. - - fileName: skeleton-display-text-small-display-text.tsx - title: Small display text - description: >- - Use this component to represent small display text such as content - headings. + - fileName: skeleton-display-text-small.tsx + title: Small + description: Use this component to represent small display text such as content headings. --- # Skeleton display text diff --git a/polaris.shopify.com/content/components/skeleton-page.md b/polaris.shopify.com/content/components/skeleton-page.md index da956d0a35d..47119a8b6a9 100644 --- a/polaris.shopify.com/content/components/skeleton-page.md +++ b/polaris.shopify.com/content/components/skeleton-page.md @@ -9,15 +9,11 @@ keywords: - page examples: - fileName: skeleton-page-with-dynamic-content.tsx - title: Page with dynamic content - description: >- - Use this component to compose a loading version of a page where the page - title and header content are dynamic, meaning, the content changes. + title: With dynamic content + description: Use this component to compose a loading version of a page where the page title and header content are dynamic, meaning, the content changes. - fileName: skeleton-page-with-static-content.tsx - title: Page with static content - description: >- - Use this component to compose a loading version of a page where the page - title and header content are known and stay the same. + title: With static content + description: Use this component to compose a loading version of a page where the page title and header content are known and stay the same. --- # Skeleton page diff --git a/polaris.shopify.com/content/components/skeleton-tabs.md b/polaris.shopify.com/content/components/skeleton-tabs.md index ba2bc6aad14..a01bd32e604 100644 --- a/polaris.shopify.com/content/components/skeleton-tabs.md +++ b/polaris.shopify.com/content/components/skeleton-tabs.md @@ -8,10 +8,10 @@ keywords: - loading - page examples: - - fileName: skeleton-tabs-simple.tsx - title: Simple skeleton tabs + - fileName: skeleton-tabs-default.tsx + title: Default - fileName: skeleton-tabs-with-a-custom-count.tsx - title: Skeleton tabs with a custom count + title: With a custom count --- # Skeleton tabs diff --git a/polaris.shopify.com/content/components/skeleton-thumbnail.md b/polaris.shopify.com/content/components/skeleton-thumbnail.md index c50a2eea420..e2e9cbc1ee7 100644 --- a/polaris.shopify.com/content/components/skeleton-thumbnail.md +++ b/polaris.shopify.com/content/components/skeleton-thumbnail.md @@ -8,17 +8,17 @@ keywords: - loading - page examples: - - fileName: skeleton-thumbnail-medium-thumbnail.tsx - title: Medium thumbnail + - fileName: skeleton-thumbnail-medium.tsx + title: Medium description: Use this component to represent medium thumbnails. - - fileName: skeleton-thumbnail-large-thumbnail.tsx - title: Large thumbnail + - fileName: skeleton-thumbnail-large.tsx + title: Large description: Use this component to represent large thumbnails. - - fileName: skeleton-thumbnail-small-thumbnail.tsx - title: Small thumbnail + - fileName: skeleton-thumbnail-small.tsx + title: Small description: Use this component to represent small thumbnails. - - fileName: skeleton-thumbnail-extra-small-thumbnail.tsx - title: Extra small thumbnail + - fileName: skeleton-thumbnail-extra-small.tsx + title: Extra small description: Use this component to represent extra small thumbnails. --- diff --git a/polaris.shopify.com/content/components/spinner.md b/polaris.shopify.com/content/components/spinner.md index 28f030b99a4..6419f9c8436 100644 --- a/polaris.shopify.com/content/components/spinner.md +++ b/polaris.shopify.com/content/components/spinner.md @@ -9,18 +9,14 @@ keywords: - progress indicator examples: - fileName: spinner-default.tsx - title: Default spinner - description: >- - Use to notify merchants that their requested action is being - processed. + title: Default + description: Use to notify merchants that their requested action is being processed. - fileName: spinner-small.tsx - title: Small spinner + title: Small description: Smaller than the default spinner. - fileName: spinner-with-focus-management.tsx - title: Spinner with focus management - description: >- - Use to direct the focus state from the control to the spinner, to the - content. + title: With focus management + description: Use to direct the focus state from the control to the spinner, to the content. --- # Spinner diff --git a/polaris.shopify.com/content/components/stack.md b/polaris.shopify.com/content/components/stack.md index 386d0980c58..1f214439aec 100644 --- a/polaris.shopify.com/content/components/stack.md +++ b/polaris.shopify.com/content/components/stack.md @@ -17,42 +17,27 @@ keywords: - stack layout - layout examples: - - fileName: stack-default-behavior.tsx - title: Default behavior - description: >- - Use to quickly lay out a horizontal row of components and maintain their - relative sizes. On small screens, children rows wrap down to additional - rows as needed. + - fileName: stack-default.tsx + title: Default + description: Use to quickly lay out a horizontal row of components and maintain their relative sizes. On small screens, children rows wrap down to additional rows as needed. - fileName: stack-non-wrapping.tsx - title: Non-wrapping Stacks - description: >- - Use to create a stack where the children will not wrap to new rows on - small screens. As noted above, the wrap option defaults to true. This - means you must explicitly set it to false to turn it off. - - fileName: stack-spacing-options.tsx - title: Spacing options - description: >- - Use to control spacing of items in a stack in standard increments. Use - tight for less spacing, loose for more spacing, or none to remove normal - spacing altogether. + title: Non-wrapping + description: Use to create a stack where the children will not wrap to new rows on small screens. As noted above, the wrap option defaults to true. This means you must explicitly set it to false to turn it off. + - fileName: stack-spacing.tsx + title: Spacing + description: Use to control spacing of items in a stack in standard increments. Use tight for less spacing, loose for more spacing, or none to remove normal spacing altogether. - fileName: stack-vertical-centering.tsx - title: Vertical centering with a stack + title: Vertical centering description: Use to vertically center a set of items that have different heights. - fileName: stack-fill-available-space-proportionally.tsx title: Fill available space proportionally - description: >- - Use to have the stack’s items fill the horizontal space in the container - but maintain their relative proportions. + description: Use to have the stack’s items fill the horizontal space in the container but maintain their relative proportions. - fileName: stack-where-items-fill-space-evenly.tsx - title: Stack where items fill space evenly - description: >- - Use to have the stack’s items fill the horizontal space in the container - and be equal widths, regardless of their content. + title: Where items fill space evenly + description: Use to have the stack’s items fill the horizontal space in the container and be equal widths, regardless of their content. - fileName: stack-where-a-single-item-fills-the-remaining-space.tsx - title: Stack where a single item fills the remaining space - description: >- - Use for aligning buttons or secondary content to the right edge of another - element, allowing it to wrap below on small screens. + title: Where a single item fills the remaining space + description: Use for aligning buttons or secondary content to the right edge of another element, allowing it to wrap below on small screens. --- # Stack diff --git a/polaris.shopify.com/content/components/subheading.md b/polaris.shopify.com/content/components/subheading.md index c59b0bd3e46..d2ce2dac3ec 100644 --- a/polaris.shopify.com/content/components/subheading.md +++ b/polaris.shopify.com/content/components/subheading.md @@ -10,11 +10,9 @@ keywords: - subsection titles - titles of subsections examples: - - fileName: subheading-typographic.tsx - title: Typographic subheading - description: >- - Used for the title of any sub-sections in top-level page - sections. + - fileName: subheading-default.tsx + title: Default + description: Used for the title of any sub-sections in top-level page sections. --- # Subheading diff --git a/polaris.shopify.com/content/components/tabs.md b/polaris.shopify.com/content/components/tabs.md index adea488efdc..16115746bc5 100644 --- a/polaris.shopify.com/content/components/tabs.md +++ b/polaris.shopify.com/content/components/tabs.md @@ -12,20 +12,16 @@ keywords: - scrollable examples: - fileName: tabs-default.tsx - title: Default tabs - description: >- - Use for most cases, especially when the number of tabs may be more than - three. + title: Default + description: Use for most cases, especially when the number of tabs may be more than three. - fileName: tabs-fitted.tsx - title: Fitted tabs - description: >- - Use when tabs contain a few (2 or 3) items within a narrow - column. + title: Fitted + description: Use when tabs contain a few (2 or 3) items within a narrow column. - fileName: tabs-with-badge-content.tsx - title: Tabs with badge content + title: With badge content description: Use to inform a piece of information about the tabs. - fileName: tabs-with-custom-disclosure.tsx - title: Tabs with custom disclosure + title: With custom disclosure description: Use to provide information about the popover contents --- @@ -79,4 +75,3 @@ And for the customers section, the tabs are: Where possible, follow this pattern when writing tabs. ---- diff --git a/polaris.shopify.com/content/components/tag.md b/polaris.shopify.com/content/components/tag.md index 460ba487a99..cdefe35527a 100644 --- a/polaris.shopify.com/content/components/tag.md +++ b/polaris.shopify.com/content/components/tag.md @@ -11,29 +11,23 @@ keywords: - keywords examples: - fileName: tag-default.tsx - title: Default tag + title: Default description: Use to signify the attributes of an object. - fileName: tag-removable.tsx - title: Removable tag + title: Removable description: Use to allow merchants to remove attributes from an object. - fileName: tag-clickable.tsx - title: Clickable tag + title: Clickable description: Use to allow merchants to add attributes to an object. - fileName: tag-with-link.tsx - title: Tag with link - description: >- - Use to allow merchants to navigate to a resource. For example a customer - segment or a smart collection + title: With link + description: Use to allow merchants to navigate to a resource. For example a customer segment or a smart collection - fileName: tag-with-custom-content.tsx - title: Tag with custom content - description: >- - Use when a tag needs to be visually distinguished from others, like when - it's added automatically. + title: With custom content + description: Use when a tag needs to be visually distinguished from others, like when it's added automatically. - fileName: tag-removable-with-link.tsx - title: Removable tag with link - description: >- - A removable attribute to an object that allows merchants to navigate to a - resource. + title: Removable with link + description: A removable attribute to an object that allows merchants to navigate to a resource. --- # Tag diff --git a/polaris.shopify.com/content/components/text-container.md b/polaris.shopify.com/content/components/text-container.md index 6aa8e55f863..acc5836c9b0 100644 --- a/polaris.shopify.com/content/components/text-container.md +++ b/polaris.shopify.com/content/components/text-container.md @@ -12,18 +12,14 @@ keywords: - padding examples: - fileName: text-container-default.tsx - title: Default text container + title: Default description: Use this component for default vertical spacing. - fileName: text-container-tight.tsx - title: Tight text container - description: >- - Use the tight spacing option to relate content topics to each - other. + title: Tight + description: Use the tight spacing option to relate content topics to each other. - fileName: text-container-loose.tsx - title: Loose text container - description: >- - Use the loose spacing option to separate concepts that are independent of - each other. + title: Loose + description: Use the loose spacing option to separate concepts that are independent of each other. --- # Text container diff --git a/polaris.shopify.com/content/components/text-field.md b/polaris.shopify.com/content/components/text-field.md index 9e64f051a9a..aa4cc56506d 100644 --- a/polaris.shopify.com/content/components/text-field.md +++ b/polaris.shopify.com/content/components/text-field.md @@ -42,119 +42,65 @@ keywords: - icon action examples: - fileName: text-field-default.tsx - title: Default text field - description: >- - Use to allow merchants to provide text input when the expected input is - short. For longer input, use the auto grow or multiline - options. - - fileName: text-field-number-field.tsx - title: Number field - description: >- - Use when input text should be a number.This will display the right - keyboard on mobile devices. This will display the right keyboard - on mobile devices. - - fileName: text-field-email-field.tsx - title: Email field - description: >- - Use when the text input should be an email address.This will display the - right keyboard on mobile devices. This will display the right - keyboard on mobile devices. + title: Default + description: Use to allow merchants to provide text input when the expected input is short. For longer input, use the auto grow or multiline options. + - fileName: text-field-number.tsx + title: Number + description: Use when input text should be a number. + - fileName: text-field-email.tsx + title: Email + description: Use when the text input should be an email address. - fileName: text-field-multiline.tsx - title: Multiline text field - description: >- - Use when the expected input could be more than one line. The field will - automatically grow to accommodate additional text. + title: Multiline + description: Use when the expected input could be more than one line. The field will automatically grow to accommodate additional text. - fileName: text-field-with-hidden-label.tsx - title: Text field with hidden label - description: >- - Use to visually hide the label when the text field’s purpose is clear from - context. The label will remain available to screen readers. Use this - option with care. In almost all cases, show the label. + title: With hidden label + description: Use to visually hide the label when the text field’s purpose is clear from context. The label will remain available to screen readers. Use this option with care. In almost all cases, show the label. - fileName: text-field-with-label-action.tsx - title: Text field with label action - description: >- - Use when an optional, secondary action is closely associated with a text - field. For example, on a field for entering a customs tariff code, a label - action might be to look up the appropriate code from a table. + title: With label action + description: Use when an optional, secondary action is closely associated with a text field. For example, on a field for entering a customs tariff code, a label action might be to look up the appropriate code from a table. - fileName: text-field-with-right-aligned-text.tsx - title: TextField with right aligned text + title: With right aligned text description: Use when input text should be aligned right. - fileName: text-field-with-placeholder-text.tsx - title: Text field with placeholder text - description: >- - Use to provide a short, non-essential hint about the expected input. - Placeholder text is low-contrast, so don’t rely on it for important - information. + title: With placeholder text + description: Use to provide a short, non-essential hint about the expected input. Placeholder text is low-contrast, so don’t rely on it for important information. - fileName: text-field-with-help-text.tsx - title: Text field with help text - description: >- - Use to show short instructional content below the text field. Help text - works to help merchants understand how to fix errors that result from - incorrect formatting (such as dates or passwords with specific character - requirements). If more explanation is needed, link to the Shopify Help - Center. + title: With help text + description: Use to show short instructional content below the text field. Help text works to help merchants understand how to fix errors that result from incorrect formatting (such as dates or passwords with specific character requirements). If more explanation is needed, link to the Shopify Help Center. - fileName: text-field-with-prefix-or-suffix.tsx - title: Text field with prefix or suffix - description: >- - Use as a special form of help text that works best inline.Use a prefix for - things like currency symbols (“$”, “¥”, “£”).Use suffix for things like - units of measure (“in”, “cm”). + title: With prefix or suffix + description: Use as a special form of help text that works best inline. Use a prefix for things like currency symbols (“\$”, “¥”, “£”). Use suffix for things like units of measure (“in”, “cm”). - fileName: text-field-with-vertical-content.tsx - title: Text field with vertical content - description: >- - Use to include custom vertical content above the input value, like - selected tags. + title: With vertical content + description: Use to include custom vertical content above the input value, like selected tags. - fileName: text-field-with-connected-fields.tsx - title: Text field with connected fields - description: >- - Use when a text field and several related fields make up a logical unit.If - inputting weight as a number and a separate unit of measurement, use a - text field with a selector (like “kg” or “lb”) as a connected - field. If inputting weight as a number and a separate unit of - measurement, use a text field with a selector (like “kg” or “lb”) as a - connected field. + title: With connected fields + description: Use when a text field and several related fields make up a logical unit. If inputting weight as a number and a separate unit of measurement, use a text field with a [select dropdown menu](https://polaris.shopify.com/components/select) (for example “kg”, “lb”) as a connected field. - fileName: text-field-with-validation-error.tsx - title: Text field with validation error - description: >- - Use to let merchants know if their input is valid or if there’s an error. - Whenever possible, validate input as soon as merchants have finished - interacting with a field (but not before). If a field already has an - error, validate and remove errors as merchants type so they can - immediately see when an error has been fixed. + title: With validation error + description: Use to let merchants know if their input is valid or if there’s an error. Whenever possible, validate input as soon as merchants have finished interacting with a field (but not before). If a field already has an error, validate and remove errors as merchants type so they can immediately see when an error has been fixed. - fileName: text-field-with-separate-validation-error.tsx - title: Text field with separate validation error - description: >- - Use to let merchants know when their text field input is invalid in the - context of a group of form inputs that the text field depends on.To render - an invalid text field and its validation error separately: + title: With separate validation error + description: Use to let merchants know when their text field input is invalid in the context of a group of form inputs that the text field depends on. - fileName: text-field-disabled.tsx - title: Disabled text field - description: >- - Use to show that a textfield is not available for interaction. Most often - used in forms when information is required only in a particular state. For - example, the text field next to Other in a choice list when Other is not - selected. + title: Disabled + description: Use to show that a textfield is not available for interaction. Most often used in forms when information is required only in a particular state. For example, the text field next to Other in a choice list when Other is not selected. - fileName: text-field-with-character-count.tsx - title: Text field with character count - description: >- - Use to display the current number of characters in a text field. Use in - conjunction with max length to display the current remaining number of - characters in the text field. + title: With character count + description: Use to display the current number of characters in a text field. Use in conjunction with max length to display the current remaining number of characters in the text field. - fileName: text-field-with-clear-button.tsx - title: Text field with clear button + title: With clear button description: Use to allow merchants to clear the content from a text field. - fileName: text-field-with-monospaced-font.tsx - title: Text field with monospaced font + title: With monospaced font description: Use to apply a monospaced font to the TextField - fileName: text-field-with-value-selected-on-focus.tsx - title: Text field with value selected on focus + title: With value selected on focus description: Use to select all text inside TextField on focus. - fileName: text-field-with-inline-suggestion.tsx - title: Text field with inline suggestion - description: >- - Use to provide an autocomplete suggestion inline with the input value. See - the combobox component's tag multi-select example for full implementation - of the inline autocomplete pattern. + title: With inline suggestion + description: Use to provide an autocomplete suggestion inline with the input value. See the combobox component's tag multi-select example for full implementation of the inline autocomplete pattern. --- # Text field diff --git a/polaris.shopify.com/content/components/text-style.md b/polaris.shopify.com/content/components/text-style.md index 3c9e329aad8..49ae84dfb0e 100644 --- a/polaris.shopify.com/content/components/text-style.md +++ b/polaris.shopify.com/content/components/text-style.md @@ -20,37 +20,23 @@ keywords: - fields examples: - fileName: text-style-subdued.tsx - title: Subdued text style - description: >- - Use to de-emphasize a piece of text that is less important to merchants - than other nearby text. May also be used to indicate when normal content - is absent, for example, “No supplier listed”. Don’t use only for aesthetic - effect. + title: Subdued + description: Use to de-emphasize a piece of text that is less important to merchants than other nearby text. May also be used to indicate when normal content is absent, for example, “No supplier listed”. Don’t use only for aesthetic effect. - fileName: text-style-strong.tsx - title: Strong text style - description: >- - Use to mark text representing user input, or to emphasize the totals row - in a price table. + title: Strong + description: Use to mark text representing user input, or to emphasize the totals row in a price table. - fileName: text-style-positive.tsx - title: Positive text style - description: >- - Use in combination with a symbol showing an increasing value to indicate - an upward trend. + title: Positive + description: Use in combination with a symbol showing an increasing value to indicate an upward trend. - fileName: text-style-negative.tsx - title: Negative text style - description: >- - Use in combination with a symbol showing a decreasing value to indicate a - downward trend. + title: Negative + description: Use in combination with a symbol showing a decreasing value to indicate a downward trend. - fileName: text-style-warning.tsx - title: Warning text style - description: >- - Use to denote something that needs attention, or that merchants need to - take action on. + title: Warning + description: Use to denote something that needs attention, or that merchants need to take action on. - fileName: text-style-code.tsx - title: Code text style - description: >- - Use to display inline snippets of code or code-like - text. + title: Code + description: Use to display inline snippets of code or code-like text. --- # Text style diff --git a/polaris.shopify.com/content/components/thumbnail.md b/polaris.shopify.com/content/components/thumbnail.md index a264a66b1a8..2e89db6c700 100644 --- a/polaris.shopify.com/content/components/thumbnail.md +++ b/polaris.shopify.com/content/components/thumbnail.md @@ -11,25 +11,19 @@ keywords: - image preview examples: - fileName: thumbnail-default.tsx - title: Default thumbnail + title: Default description: Use as the default size. - fileName: thumbnail-extra-small.tsx - title: Extra small thumbnail - description: >- - Use to present a thumbnail in a condensed layout, such as a data table - cell or an action list item. + title: Extra small + description: Use to present a thumbnail in a condensed layout, such as a data table cell or an action list item. - fileName: thumbnail-small.tsx - title: Small thumbnail - description: >- - Use when the default size is too large for the layout, or when the - thumbnail has less importance. + title: Small + description: Use when the default size is too large for the layout, or when the thumbnail has less importance. - fileName: thumbnail-large.tsx - title: Large thumbnail - description: >- - Use when a thumbnail is a major focal point. Avoid this size in lists of - like items. + title: Large + description: Use when a thumbnail is a major focal point. Avoid this size in lists of like items. - fileName: thumbnail-with-component-source.tsx - title: Thumbnail with component source + title: With component source description: Use to render an icon inside of thumbnail. --- diff --git a/polaris.shopify.com/content/components/toast.md b/polaris.shopify.com/content/components/toast.md index 56158437a3b..6320db6c298 100644 --- a/polaris.shopify.com/content/components/toast.md +++ b/polaris.shopify.com/content/components/toast.md @@ -14,23 +14,21 @@ keywords: - iframe - duration examples: - - fileName: toast-basic.tsx - title: Basic toast - description: >- - Use to convey general confirmation or actions that aren’t critical. For - example, you might show a toast message to inform the merchant that their - recent action was successful. + - fileName: toast-default.tsx + title: Default + description: Use to convey general confirmation or actions that aren’t critical. For example, you might show a toast message to inform the merchant that their recent action was successful. - fileName: toast-multiple-messages.tsx - title: Multiple toast messages + title: Multiple messages description: Use multiple toast messages to inform the merchant about distinct actions. - fileName: toast-with-custom-duration.tsx - title: Toast with custom duration + title: With custom duration description: Use to shorten or lengthen the default duration of 5000 milliseconds. + - fileName: toast-with-action.tsx + title: With action + description: Use when a merchant has the ability to act on the message. For example, to undo a change or retry an action. - fileName: toast-error.tsx - title: Error toast - description: >- - On iOS, icons are available for cases where you want to - re-inforce the message. + title: Error + description: Although error toast is still available and used in the system, we discourage its use. Reserve it for errors not caused by merchants, like a connection issue. Error toast should convey what went wrong in plain language and should not go over 3 words. For all other error message types, follow the [error message guidelines](https://polaris.shopify.com/patterns/error-messages). --- # Toast diff --git a/polaris.shopify.com/content/components/tooltip.md b/polaris.shopify.com/content/components/tooltip.md index 3ac9cc30582..1615f59ddd8 100644 --- a/polaris.shopify.com/content/components/tooltip.md +++ b/polaris.shopify.com/content/components/tooltip.md @@ -12,12 +12,11 @@ keywords: - tap examples: - fileName: tooltip-default.tsx - title: Default tooltip - description: >- - Use only when necessary to provide an explanation for an interface - element. + title: Default + description: Use only when necessary to provide an explanation for an interface element. - fileName: tooltip-visible-only-with-child-interaction.tsx - title: Tooltip visible only with child interaction + title: Visible only with child interaction + description: Use when the tooltip overlays interactive elements when active, for example a form input. The `dismissOnMouseOut` prop prevents the tooltip from remaining active when mouse hover or focus leaves its `children` and enters the tooltip's content. --- # Tooltip diff --git a/polaris.shopify.com/content/components/top-bar.md b/polaris.shopify.com/content/components/top-bar.md index 30cf3dd2fd1..7a54b5ea6dc 100644 --- a/polaris.shopify.com/content/components/top-bar.md +++ b/polaris.shopify.com/content/components/top-bar.md @@ -16,10 +16,12 @@ keywords: - menu - logo examples: - - fileName: top-bar-with-all-of-its-elements.tsx - title: Top bar with all of its elements - - fileName: top-bar-themed-with-color-scheme.tsx - title: Top bar themed with colorScheme + - fileName: top-bar-default.tsx + title: Default + description: Use to provide structure for the top of an application. Style the top bar component using the app provider component with a theme. Providing just the `background` key for the top bar component theme will result in intelligent defaults being set for complementary colors with contrasting text. + - fileName: top-bar-with-color-scheme.tsx + title: With colorScheme + description: Provide specific keys and corresponding colors to the top bar theme for finer control. When giving more than just the `background`, providing all keys is necessary to prevent falling back to default colors. --- # Top bar diff --git a/polaris.shopify.com/content/components/video-thumbnail.md b/polaris.shopify.com/content/components/video-thumbnail.md index 95dad83e70f..c01c4fc16be 100644 --- a/polaris.shopify.com/content/components/video-thumbnail.md +++ b/polaris.shopify.com/content/components/video-thumbnail.md @@ -11,11 +11,11 @@ keywords: - education - contextual learning system examples: - - fileName: video-thumbnail-basic.tsx - title: Basic video thumbnail + - fileName: video-thumbnail-default.tsx + title: Default description: Use as a play button for a video player within a media card. - fileName: video-thumbnail-with-progress.tsx - title: Video thumbnail with progress + title: With progress description: Use to indicate the video’s play progress in relation to its duration. --- diff --git a/polaris.shopify.com/content/components/visually-hidden.md b/polaris.shopify.com/content/components/visually-hidden.md index bc8c0f45097..564c1cca485 100644 --- a/polaris.shopify.com/content/components/visually-hidden.md +++ b/polaris.shopify.com/content/components/visually-hidden.md @@ -17,15 +17,12 @@ keywords: - a11y - assistive technology examples: - - fileName: visually-hidden-heading.tsx - title: Visually hidden heading - description: >- - Always provide a heading for a major page section such as a card. In rare - cases the heading is visually redundant and the meaning is conveyed by - context. Rather than omit the heading, wrap the heading in the visually - hidden component. + - fileName: visually-hidden-default.tsx + title: Default + description: Always provide a heading for a major page section such as a card. In rare cases the heading is visually redundant and the meaning is conveyed by context. Rather than omit the heading, wrap the heading in the visually hidden component. - fileName: visually-hidden-table-headers.tsx - title: Visually hidden table headers + title: Table headers + description: Whenever one or more table columns has no need for a visible header, hide the header content rather than omitting it. Note that due to browser quirks the visually hidden component must go inside each ``. --- # Visually hidden diff --git a/polaris.shopify.com/src/pages/examples/account-connection.tsx b/polaris.shopify.com/src/pages/examples/account-connection-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/account-connection.tsx rename to polaris.shopify.com/src/pages/examples/account-connection-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/action-list-sectioned.tsx b/polaris.shopify.com/src/pages/examples/action-list-with-sections.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/action-list-sectioned.tsx rename to polaris.shopify.com/src/pages/examples/action-list-with-sections.tsx diff --git a/polaris.shopify.com/src/pages/examples/autocomplete-basic.tsx b/polaris.shopify.com/src/pages/examples/autocomplete-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/autocomplete-basic.tsx rename to polaris.shopify.com/src/pages/examples/autocomplete-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/autocomplete-multiple-sections.tsx b/polaris.shopify.com/src/pages/examples/autocomplete-with-multiple-sections.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/autocomplete-multiple-sections.tsx rename to polaris.shopify.com/src/pages/examples/autocomplete-with-multiple-sections.tsx diff --git a/polaris.shopify.com/src/pages/examples/autocomplete-multiple-tags.tsx b/polaris.shopify.com/src/pages/examples/autocomplete-with-multiple-tags.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/autocomplete-multiple-tags.tsx rename to polaris.shopify.com/src/pages/examples/autocomplete-with-multiple-tags.tsx diff --git a/polaris.shopify.com/src/pages/examples/avatar-square.tsx b/polaris.shopify.com/src/pages/examples/avatar-square.tsx new file mode 100644 index 00000000000..528d88623e9 --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/avatar-square.tsx @@ -0,0 +1,9 @@ +import { Avatar } from "@shopify/polaris"; +import React from "react"; +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function AvatarExample() { + return ; +} + +export default withPolarisExample(AvatarExample); diff --git a/polaris.shopify.com/src/pages/examples/button-basic.tsx b/polaris.shopify.com/src/pages/examples/button-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/button-basic.tsx rename to polaris.shopify.com/src/pages/examples/button-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/card-with-all-of-its-elements.tsx b/polaris.shopify.com/src/pages/examples/card-with-all-elements.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/card-with-all-of-its-elements.tsx rename to polaris.shopify.com/src/pages/examples/card-with-all-elements.tsx diff --git a/polaris.shopify.com/src/pages/examples/card-section-with-custom-react-node-title.tsx b/polaris.shopify.com/src/pages/examples/card-with-custom-react-node-title.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/card-section-with-custom-react-node-title.tsx rename to polaris.shopify.com/src/pages/examples/card-with-custom-react-node-title.tsx diff --git a/polaris.shopify.com/src/pages/examples/card-section-with-destructive-action.tsx b/polaris.shopify.com/src/pages/examples/card-with-destructive-action.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/card-section-with-destructive-action.tsx rename to polaris.shopify.com/src/pages/examples/card-with-destructive-action.tsx diff --git a/polaris.shopify.com/src/pages/examples/card-section-with-action.tsx b/polaris.shopify.com/src/pages/examples/card-with-sections-and-actions.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/card-section-with-action.tsx rename to polaris.shopify.com/src/pages/examples/card-with-sections-and-actions.tsx diff --git a/polaris.shopify.com/src/pages/examples/card-subdued-for-secondary-content.tsx b/polaris.shopify.com/src/pages/examples/card-with-subdued-for-secondary-content.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/card-subdued-for-secondary-content.tsx rename to polaris.shopify.com/src/pages/examples/card-with-subdued-for-secondary-content.tsx diff --git a/polaris.shopify.com/src/pages/examples/checkboxes-default.tsx b/polaris.shopify.com/src/pages/examples/checkbox-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/checkboxes-default.tsx rename to polaris.shopify.com/src/pages/examples/checkbox-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/choice-list-single.tsx b/polaris.shopify.com/src/pages/examples/choice-list-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/choice-list-single.tsx rename to polaris.shopify.com/src/pages/examples/choice-list-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/choice-list-single-choice-or-multi-with-children-content-always-rendered.tsx b/polaris.shopify.com/src/pages/examples/choice-list-with-children-content.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/choice-list-single-choice-or-multi-with-children-content-always-rendered.tsx rename to polaris.shopify.com/src/pages/examples/choice-list-with-children-content.tsx diff --git a/polaris.shopify.com/src/pages/examples/choice-list-single-choice-or-multi-with-children-content-only-rendered-when-choice-is-selected.tsx b/polaris.shopify.com/src/pages/examples/choice-list-with-dynamic-children-content.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/choice-list-single-choice-or-multi-with-children-content-only-rendered-when-choice-is-selected.tsx rename to polaris.shopify.com/src/pages/examples/choice-list-with-dynamic-children-content.tsx diff --git a/polaris.shopify.com/src/pages/examples/choice-list-single-with-error.tsx b/polaris.shopify.com/src/pages/examples/choice-list-with-error.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/choice-list-single-with-error.tsx rename to polaris.shopify.com/src/pages/examples/choice-list-with-error.tsx diff --git a/polaris.shopify.com/src/pages/examples/choice-list-multi.tsx b/polaris.shopify.com/src/pages/examples/choice-list-with-multi-choice.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/choice-list-multi.tsx rename to polaris.shopify.com/src/pages/examples/choice-list-with-multi-choice.tsx diff --git a/polaris.shopify.com/src/pages/examples/color-pickerpicker-with-transparent-value-full-width.tsx b/polaris.shopify.com/src/pages/examples/color-picker-with-transparent-value-full-width.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/color-pickerpicker-with-transparent-value-full-width.tsx rename to polaris.shopify.com/src/pages/examples/color-picker-with-transparent-value-full-width.tsx diff --git a/polaris.shopify.com/src/pages/examples/color-pickerpicker-with-transparent-value.tsx b/polaris.shopify.com/src/pages/examples/color-picker-with-transparent-value.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/color-pickerpicker-with-transparent-value.tsx rename to polaris.shopify.com/src/pages/examples/color-picker-with-transparent-value.tsx diff --git a/polaris.shopify.com/src/pages/examples/combobox-single-select-autocomplete.tsx b/polaris.shopify.com/src/pages/examples/combobox-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/combobox-single-select-autocomplete.tsx rename to polaris.shopify.com/src/pages/examples/combobox-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/combobox-autocomplete-with-loading.tsx b/polaris.shopify.com/src/pages/examples/combobox-with-loading.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/combobox-autocomplete-with-loading.tsx rename to polaris.shopify.com/src/pages/examples/combobox-with-loading.tsx diff --git a/polaris.shopify.com/src/pages/examples/combobox-multi-select-autocomplete.tsx b/polaris.shopify.com/src/pages/examples/combobox-with-manual-selection.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/combobox-multi-select-autocomplete.tsx rename to polaris.shopify.com/src/pages/examples/combobox-with-manual-selection.tsx diff --git a/polaris.shopify.com/src/pages/examples/combobox-with-multi-select-and-manual-selection.tsx b/polaris.shopify.com/src/pages/examples/combobox-with-multi-select-and-manual-selection.tsx new file mode 100644 index 00000000000..7d1cae70fb0 --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/combobox-with-multi-select-and-manual-selection.tsx @@ -0,0 +1,127 @@ +import { + Tag, + Listbox, + Combobox, + Icon, + TextContainer, + Stack, +} from "@shopify/polaris"; +import { SearchMinor } from "@shopify/polaris-icons"; +import { useState, useCallback, useMemo } from "react"; +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function MultiManualComboboxExample() { + const deselectedOptions = useMemo( + () => [ + { value: "rustic", label: "Rustic" }, + { value: "antique", label: "Antique" }, + { value: "vinyl", label: "Vinyl" }, + { value: "vintage", label: "Vintage" }, + { value: "refurbished", label: "Refurbished" }, + ], + [] + ); + + const [selectedOptions, setSelectedOptions] = useState([]); + const [inputValue, setInputValue] = useState(""); + const [options, setOptions] = useState(deselectedOptions); + + const updateText = useCallback( + (value) => { + setInputValue(value); + + if (value === "") { + setOptions(deselectedOptions); + return; + } + + const filterRegex = new RegExp(value, "i"); + const resultOptions = deselectedOptions.filter((option) => + option.label.match(filterRegex) + ); + setOptions(resultOptions); + }, + [deselectedOptions] + ); + + const updateSelection = useCallback( + (selected) => { + if (selectedOptions.includes(selected)) { + setSelectedOptions( + selectedOptions.filter((option) => option !== selected) + ); + } else { + setSelectedOptions([...selectedOptions, selected]); + } + + const matchedOption = options.find((option) => { + return option.value.match(selected); + }); + + updateText(""); + }, + [options, selectedOptions] + ); + + const removeTag = useCallback( + (tag) => () => { + const options = [...selectedOptions]; + options.splice(options.indexOf(tag), 1); + setSelectedOptions(options); + }, + [selectedOptions] + ); + + const tagsMarkup = selectedOptions.map((option) => ( + + {option} + + )); + + const optionsMarkup = + options.length > 0 + ? options.map((option) => { + const { label, value } = option; + + return ( + + {label} + + ); + }) + : null; + + return ( +
+ } + onChange={updateText} + label="Search tags" + labelHidden + value={inputValue} + placeholder="Search tags" + /> + } + > + {optionsMarkup ? ( + + {optionsMarkup} + + ) : null} + + + {tagsMarkup} + +
+ ); +} + +export default withPolarisExample(MultiManualComboboxExample); diff --git a/polaris.shopify.com/src/pages/examples/combobox-multi-select-autocomplete-with-vertical-content.tsx b/polaris.shopify.com/src/pages/examples/combobox-with-multi-select-and-vertical-content.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/combobox-multi-select-autocomplete-with-vertical-content.tsx rename to polaris.shopify.com/src/pages/examples/combobox-with-multi-select-and-vertical-content.tsx diff --git a/polaris.shopify.com/src/pages/examples/combobox-with-multi-select.tsx b/polaris.shopify.com/src/pages/examples/combobox-with-multi-select.tsx new file mode 100644 index 00000000000..002ff6b991b --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/combobox-with-multi-select.tsx @@ -0,0 +1,128 @@ +import { + Stack, + Tag, + Listbox, + Combobox, + Icon, + TextContainer, +} from "@shopify/polaris"; + +import { SearchMinor } from "@shopify/polaris-icons"; + +import { useState, useCallback, useMemo } from "react"; + +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function MultiAutoComboboxExample() { + const deselectedOptions = useMemo( + () => [ + { value: "rustic", label: "Rustic" }, + { value: "antique", label: "Antique" }, + { value: "vinyl", label: "Vinyl" }, + { value: "vintage", label: "Vintage" }, + { value: "refurbished", label: "Refurbished" }, + ], + [] + ); + + const [selectedOptions, setSelectedOptions] = useState([]); + const [inputValue, setInputValue] = useState(""); + const [options, setOptions] = useState(deselectedOptions); + + const updateText = useCallback( + (value) => { + setInputValue(value); + + if (value === "") { + setOptions(deselectedOptions); + return; + } + + const filterRegex = new RegExp(value, "i"); + const resultOptions = deselectedOptions.filter((option) => + option.label.match(filterRegex) + ); + setOptions(resultOptions); + }, + [deselectedOptions] + ); + + const updateSelection = useCallback( + (selected) => { + if (selectedOptions.includes(selected)) { + setSelectedOptions( + selectedOptions.filter((option) => option !== selected) + ); + } else { + setSelectedOptions([...selectedOptions, selected]); + } + + const matchedOption = options.find((option) => { + return option.value.match(selected); + }); + + updateText(""); + }, + [options, selectedOptions] + ); + + const removeTag = useCallback( + (tag) => () => { + const options = [...selectedOptions]; + options.splice(options.indexOf(tag), 1); + setSelectedOptions(options); + }, + [selectedOptions] + ); + + const tagsMarkup = selectedOptions.map((option) => ( + + {option} + + )); + + const optionsMarkup = + options.length > 0 + ? options.map((option) => { + const { label, value } = option; + + return ( + + {label} + + ); + }) + : null; + + return ( +
+ } + onChange={updateText} + label="Search tags" + labelHidden + value={inputValue} + placeholder="Search tags" + /> + } + > + {optionsMarkup ? ( + {optionsMarkup} + ) : null} + + + {tagsMarkup} + +
+ ); +} + +export default withPolarisExample(MultiAutoComboboxExample); diff --git a/polaris.shopify.com/src/pages/examples/contextual-save-bar-during-creation.tsx b/polaris.shopify.com/src/pages/examples/contextual-save-bar-during-creation.tsx deleted file mode 100644 index 16ab4eae0d3..00000000000 --- a/polaris.shopify.com/src/pages/examples/contextual-save-bar-during-creation.tsx +++ /dev/null @@ -1,31 +0,0 @@ -import { Frame, ContextualSaveBar } from "@shopify/polaris"; -import React from "react"; -import { withPolarisExample } from "../../components/PolarisExamplePage"; - -function Example() { - return ( -
- - console.log("add form submit logic"), - loading: false, - disabled: false, - }} - discardAction={{ - onAction: () => console.log("add clear form logic"), - }} - /> - -
- ); -} - -export default withPolarisExample(Example); diff --git a/polaris.shopify.com/src/pages/examples/contextual-save-bar-full-width.tsx b/polaris.shopify.com/src/pages/examples/contextual-save-bar-with-full-width.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/contextual-save-bar-full-width.tsx rename to polaris.shopify.com/src/pages/examples/contextual-save-bar-with-full-width.tsx diff --git a/polaris.shopify.com/src/pages/examples/drop-zone-with-file-upload.tsx b/polaris.shopify.com/src/pages/examples/drop-zone-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/drop-zone-with-file-upload.tsx rename to polaris.shopify.com/src/pages/examples/drop-zone-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/exception-list-with-icon.tsx b/polaris.shopify.com/src/pages/examples/exception-list-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/exception-list-with-icon.tsx rename to polaris.shopify.com/src/pages/examples/exception-list-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/filters-all-disabled.tsx b/polaris.shopify.com/src/pages/examples/filters-disabled.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/filters-all-disabled.tsx rename to polaris.shopify.com/src/pages/examples/filters-disabled.tsx diff --git a/polaris.shopify.com/src/pages/examples/footer-help-box.tsx b/polaris.shopify.com/src/pages/examples/footer-help-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/footer-help-box.tsx rename to polaris.shopify.com/src/pages/examples/footer-help-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/grid-three-thirds.tsx b/polaris.shopify.com/src/pages/examples/grid-three-one-third-column.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/grid-three-thirds.tsx rename to polaris.shopify.com/src/pages/examples/grid-three-one-third-column.tsx diff --git a/polaris.shopify.com/src/pages/examples/grid-two-third-one-third.tsx b/polaris.shopify.com/src/pages/examples/grid-two-thirds-and-one-third-column.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/grid-two-third-one-third.tsx rename to polaris.shopify.com/src/pages/examples/grid-two-thirds-and-one-third-column.tsx diff --git a/polaris.shopify.com/src/pages/examples/heading-typographic.tsx b/polaris.shopify.com/src/pages/examples/heading-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/heading-typographic.tsx rename to polaris.shopify.com/src/pages/examples/heading-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/icon-user-provided-with-color-and-current-color.tsx b/polaris.shopify.com/src/pages/examples/icon-with-custom-svg-and-color.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/icon-user-provided-with-color-and-current-color.tsx rename to polaris.shopify.com/src/pages/examples/icon-with-custom-svg-and-color.tsx diff --git a/polaris.shopify.com/src/pages/examples/icon-user-provided.tsx b/polaris.shopify.com/src/pages/examples/icon-with-custom-svg.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/icon-user-provided.tsx rename to polaris.shopify.com/src/pages/examples/icon-with-custom-svg.tsx diff --git a/polaris.shopify.com/src/pages/examples/index-table-simple.tsx b/polaris.shopify.com/src/pages/examples/index-table-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/index-table-simple.tsx rename to polaris.shopify.com/src/pages/examples/index-table-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/index-table-flush.tsx b/polaris.shopify.com/src/pages/examples/index-table-flush.tsx new file mode 100644 index 00000000000..413afa5040f --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/index-table-flush.tsx @@ -0,0 +1,77 @@ +import { + IndexTable, + TextStyle, + Card, + useIndexResourceState, +} from "@shopify/polaris"; +import React from "react"; +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function SimpleFlushIndexTableExample() { + const customers = [ + { + id: "3411", + url: "customers/341", + name: "Mae Jemison", + location: "Decatur, USA", + orders: 20, + amountSpent: "$2,400", + }, + { + id: "2561", + url: "customers/256", + name: "Ellen Ochoa", + location: "Los Angeles, USA", + orders: 30, + amountSpent: "$140", + }, + ]; + const resourceName = { + singular: "customer", + plural: "customers", + }; + + const { selectedResources, allResourcesSelected, handleSelectionChange } = + useIndexResourceState(customers); + + const rowMarkup = customers.map( + ({ id, name, location, orders, amountSpent }, index) => ( + + + {name} + + {location} + {orders} + {amountSpent} + + ) + ); + + return ( + + + {rowMarkup} + + + ); +} + +export default withPolarisExample(SimpleFlushIndexTableExample); diff --git a/polaris.shopify.com/src/pages/examples/index-table-simple-small-screen.tsx b/polaris.shopify.com/src/pages/examples/index-table-small-screen.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/index-table-simple-small-screen.tsx rename to polaris.shopify.com/src/pages/examples/index-table-small-screen.tsx diff --git a/polaris.shopify.com/src/pages/examples/index-table-with-clickable-button-column.tsx b/polaris.shopify.com/src/pages/examples/index-table-with-clickable-button-column.tsx new file mode 100644 index 00000000000..ae837cd22ef --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/index-table-with-clickable-button-column.tsx @@ -0,0 +1,84 @@ +import { + IndexTable, + TextStyle, + Card, + Button, + useIndexResourceState, +} from "@shopify/polaris"; +import React from "react"; +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function ClickThroughButtonIndexTableExample() { + const customers = [ + { + id: "3411", + url: "customers/341", + name: "Mae Jemison", + location: "Decatur, USA", + orders: 20, + amountSpent: "$2,400", + }, + { + id: "2561", + url: "customers/256", + name: "Ellen Ochoa", + location: "Los Angeles, USA", + orders: 30, + amountSpent: "$140", + }, + ]; + const resourceName = { + singular: "customer", + plural: "customers", + }; + + const { selectedResources, allResourcesSelected, handleSelectionChange } = + useIndexResourceState(customers); + + const rowMarkup = customers.map( + ({ id, url, name, location, orders, amountSpent }, index) => ( + + + + + {location} + {orders} + {amountSpent} + + ) + ); + + return ( + + + {rowMarkup} + + + ); +} + +export default withPolarisExample(ClickThroughButtonIndexTableExample); diff --git a/polaris.shopify.com/src/pages/examples/index-table-with-row-navigation-link.tsx b/polaris.shopify.com/src/pages/examples/index-table-with-row-navigation-link.tsx new file mode 100644 index 00000000000..9862fe4544d --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/index-table-with-row-navigation-link.tsx @@ -0,0 +1,84 @@ +import { + IndexTable, + TextStyle, + Card, + Link, + useIndexResourceState, +} from "@shopify/polaris"; +import React from "react"; +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function ClickThroughLinkIndexTableExample() { + const customers = [ + { + id: "3411", + url: "customers/341", + name: "Mae Jemison", + location: "Decatur, USA", + orders: 20, + amountSpent: "$2,400", + }, + { + id: "2561", + url: "customers/256", + name: "Ellen Ochoa", + location: "Los Angeles, USA", + orders: 30, + amountSpent: "$140", + }, + ]; + const resourceName = { + singular: "customer", + plural: "customers", + }; + + const { selectedResources, allResourcesSelected, handleSelectionChange } = + useIndexResourceState(customers); + + const rowMarkup = customers.map( + ({ id, url, name, location, orders, amountSpent }, index) => ( + + + console.log(`Clicked ${name}`)} + > + {name} + + + {location} + {orders} + {amountSpent} + + ) + ); + + return ( + + + {rowMarkup} + + + ); +} + +export default withPolarisExample(ClickThroughLinkIndexTableExample); diff --git a/polaris.shopify.com/src/pages/examples/inline-error-basic.tsx b/polaris.shopify.com/src/pages/examples/inline-error-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/inline-error-basic.tsx rename to polaris.shopify.com/src/pages/examples/inline-error-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/layout-annotated-with-sections.tsx b/polaris.shopify.com/src/pages/examples/layout-annotated-with-sections.tsx new file mode 100644 index 00000000000..6a35fd9bcfb --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/layout-annotated-with-sections.tsx @@ -0,0 +1,53 @@ +import { + Page, + Layout, + Card, + FormLayout, + TextField, + TextContainer, + TextStyle, + Heading, +} from "@shopify/polaris"; +import React from "react"; +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function LayoutExample() { + return ( + + + +
+ + Store details +

+ + Shopify and your customers will use this information to + contact you. + +

+ +
+ + + + + {}} + autoComplete="off" + /> + {}} + autoComplete="email" + /> + + + + + + ); +} + +export default withPolarisExample(LayoutExample); diff --git a/polaris.shopify.com/src/pages/examples/link-defaults.tsx b/polaris.shopify.com/src/pages/examples/link-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/link-defaults.tsx rename to polaris.shopify.com/src/pages/examples/link-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/listbox-basic.tsx b/polaris.shopify.com/src/pages/examples/listbox-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/listbox-basic.tsx rename to polaris.shopify.com/src/pages/examples/listbox-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/media-card-basic.tsx b/polaris.shopify.com/src/pages/examples/media-card-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/media-card-basic.tsx rename to polaris.shopify.com/src/pages/examples/media-card-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/media-card-basic-with-small-visual.tsx b/polaris.shopify.com/src/pages/examples/media-card-with-small-visual.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/media-card-basic-with-small-visual.tsx rename to polaris.shopify.com/src/pages/examples/media-card-with-small-visual.tsx diff --git a/polaris.shopify.com/src/pages/examples/modal-basic.tsx b/polaris.shopify.com/src/pages/examples/modal-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/modal-basic.tsx rename to polaris.shopify.com/src/pages/examples/modal-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/navigation-basic.tsx b/polaris.shopify.com/src/pages/examples/navigation-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/navigation-basic.tsx rename to polaris.shopify.com/src/pages/examples/navigation-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/navigation-with-an-active-root-item-with-secondary-items.tsx b/polaris.shopify.com/src/pages/examples/navigation-with-an-active-root-item-with-secondary-navigation-items.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/navigation-with-an-active-root-item-with-secondary-items.tsx rename to polaris.shopify.com/src/pages/examples/navigation-with-an-active-root-item-with-secondary-navigation-items.tsx diff --git a/polaris.shopify.com/src/pages/examples/option-list-simple.tsx b/polaris.shopify.com/src/pages/examples/option-list-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/option-list-simple.tsx rename to polaris.shopify.com/src/pages/examples/option-list-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/page-actions-with-custom-primary-action.tsx b/polaris.shopify.com/src/pages/examples/page-actions-with-custom-primary-action.tsx new file mode 100644 index 00000000000..8a6ce9cbb4b --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/page-actions-with-custom-primary-action.tsx @@ -0,0 +1,29 @@ +import { PageActions, Button } from "@shopify/polaris"; +import React from "react"; +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function PageExample() { + return ( + + Save + + } + secondaryActions={[ + { + content: "Delete", + destructive: true, + }, + ]} + /> + ); +} + +export default withPolarisExample(PageExample); diff --git a/polaris.shopify.com/src/pages/examples/page-with-all-header-elements.tsx b/polaris.shopify.com/src/pages/examples/page-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/page-with-all-header-elements.tsx rename to polaris.shopify.com/src/pages/examples/page-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/page-with-content-after-title-title-metadata.tsx b/polaris.shopify.com/src/pages/examples/page-with-content-after-title.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/page-with-content-after-title-title-metadata.tsx rename to polaris.shopify.com/src/pages/examples/page-with-content-after-title.tsx diff --git a/polaris.shopify.com/src/pages/examples/range-slider-dual-thumb.tsx b/polaris.shopify.com/src/pages/examples/range-slider-with-dual-thumb.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/range-slider-dual-thumb.tsx rename to polaris.shopify.com/src/pages/examples/range-slider-with-dual-thumb.tsx diff --git a/polaris.shopify.com/src/pages/examples/range-slider-min-and-max-control.tsx b/polaris.shopify.com/src/pages/examples/range-slider-with-min-and-max.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/range-slider-min-and-max-control.tsx rename to polaris.shopify.com/src/pages/examples/range-slider-with-min-and-max.tsx diff --git a/polaris.shopify.com/src/pages/examples/range-slider-prefix-and-suffix-elements.tsx b/polaris.shopify.com/src/pages/examples/range-slider-with-prefix-and-suffix.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/range-slider-prefix-and-suffix-elements.tsx rename to polaris.shopify.com/src/pages/examples/range-slider-with-prefix-and-suffix.tsx diff --git a/polaris.shopify.com/src/pages/examples/range-slider-step-incremented-control.tsx b/polaris.shopify.com/src/pages/examples/range-slider-with-steps.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/range-slider-step-incremented-control.tsx rename to polaris.shopify.com/src/pages/examples/range-slider-with-steps.tsx diff --git a/polaris.shopify.com/src/pages/examples/resource-item-simple.tsx b/polaris.shopify.com/src/pages/examples/resource-item-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/resource-item-simple.tsx rename to polaris.shopify.com/src/pages/examples/resource-item-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/resource-item-item-with-media.tsx b/polaris.shopify.com/src/pages/examples/resource-item-with-media.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/resource-item-item-with-media.tsx rename to polaris.shopify.com/src/pages/examples/resource-item-with-media.tsx diff --git a/polaris.shopify.com/src/pages/examples/resource-item-item-with-shortcut-actions.tsx b/polaris.shopify.com/src/pages/examples/resource-item-with-shortcut-actions.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/resource-item-item-with-shortcut-actions.tsx rename to polaris.shopify.com/src/pages/examples/resource-item-with-shortcut-actions.tsx diff --git a/polaris.shopify.com/src/pages/examples/resource-item-item-with-vertical-alignment.tsx b/polaris.shopify.com/src/pages/examples/resource-item-with-vertical-alignment.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/resource-item-item-with-vertical-alignment.tsx rename to polaris.shopify.com/src/pages/examples/resource-item-with-vertical-alignment.tsx diff --git a/polaris.shopify.com/src/pages/examples/resource-list-simple.tsx b/polaris.shopify.com/src/pages/examples/resource-list-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/resource-list-simple.tsx rename to polaris.shopify.com/src/pages/examples/resource-list-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/scrollable-default-container.tsx b/polaris.shopify.com/src/pages/examples/scrollable-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/scrollable-default-container.tsx rename to polaris.shopify.com/src/pages/examples/scrollable-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/scrollable-scroll-to-child-component.tsx b/polaris.shopify.com/src/pages/examples/scrollable-to-child-component.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/scrollable-scroll-to-child-component.tsx rename to polaris.shopify.com/src/pages/examples/scrollable-to-child-component.tsx diff --git a/polaris.shopify.com/src/pages/examples/sheet-basic.tsx b/polaris.shopify.com/src/pages/examples/sheet-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/sheet-basic.tsx rename to polaris.shopify.com/src/pages/examples/sheet-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-body-text-default-paragraph.tsx b/polaris.shopify.com/src/pages/examples/skeleton-body-text-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-body-text-default-paragraph.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-body-text-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-display-text-extra-large-display-text.tsx b/polaris.shopify.com/src/pages/examples/skeleton-display-text-extra-large.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-display-text-extra-large-display-text.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-display-text-extra-large.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-display-text-medium-and-large-display-text.tsx b/polaris.shopify.com/src/pages/examples/skeleton-display-text-medium-and-large.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-display-text-medium-and-large-display-text.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-display-text-medium-and-large.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-display-text-small-display-text.tsx b/polaris.shopify.com/src/pages/examples/skeleton-display-text-small.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-display-text-small-display-text.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-display-text-small.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-tabs-simple.tsx b/polaris.shopify.com/src/pages/examples/skeleton-tabs-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-tabs-simple.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-tabs-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-thumbnail-extra-small-thumbnail.tsx b/polaris.shopify.com/src/pages/examples/skeleton-thumbnail-extra-small.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-thumbnail-extra-small-thumbnail.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-thumbnail-extra-small.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-thumbnail-large-thumbnail.tsx b/polaris.shopify.com/src/pages/examples/skeleton-thumbnail-large.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-thumbnail-large-thumbnail.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-thumbnail-large.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-thumbnail-medium-thumbnail.tsx b/polaris.shopify.com/src/pages/examples/skeleton-thumbnail-medium.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-thumbnail-medium-thumbnail.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-thumbnail-medium.tsx diff --git a/polaris.shopify.com/src/pages/examples/skeleton-thumbnail-small-thumbnail.tsx b/polaris.shopify.com/src/pages/examples/skeleton-thumbnail-small.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/skeleton-thumbnail-small-thumbnail.tsx rename to polaris.shopify.com/src/pages/examples/skeleton-thumbnail-small.tsx diff --git a/polaris.shopify.com/src/pages/examples/stack-default-behavior.tsx b/polaris.shopify.com/src/pages/examples/stack-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/stack-default-behavior.tsx rename to polaris.shopify.com/src/pages/examples/stack-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/stack-spacing-options.tsx b/polaris.shopify.com/src/pages/examples/stack-spacing.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/stack-spacing-options.tsx rename to polaris.shopify.com/src/pages/examples/stack-spacing.tsx diff --git a/polaris.shopify.com/src/pages/examples/subheading-typographic.tsx b/polaris.shopify.com/src/pages/examples/subheading-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/subheading-typographic.tsx rename to polaris.shopify.com/src/pages/examples/subheading-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/text-field-email-field.tsx b/polaris.shopify.com/src/pages/examples/text-field-email.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/text-field-email-field.tsx rename to polaris.shopify.com/src/pages/examples/text-field-email.tsx diff --git a/polaris.shopify.com/src/pages/examples/text-field-number-field.tsx b/polaris.shopify.com/src/pages/examples/text-field-number.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/text-field-number-field.tsx rename to polaris.shopify.com/src/pages/examples/text-field-number.tsx diff --git a/polaris.shopify.com/src/pages/examples/toast-basic.tsx b/polaris.shopify.com/src/pages/examples/toast-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/toast-basic.tsx rename to polaris.shopify.com/src/pages/examples/toast-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/toast-with-action.tsx b/polaris.shopify.com/src/pages/examples/toast-with-action.tsx new file mode 100644 index 00000000000..c9714007b9f --- /dev/null +++ b/polaris.shopify.com/src/pages/examples/toast-with-action.tsx @@ -0,0 +1,34 @@ +import { Toast, Frame, Page, Button } from "@shopify/polaris"; +import { useState, useCallback } from "react"; +import { withPolarisExample } from "../../components/PolarisExamplePage"; + +function ToastWithActionExample() { + const [active, setActive] = useState(false); + + const toggleActive = useCallback(() => setActive((active) => !active), []); + + const toastMarkup = active ? ( + {}, + }} + duration={10000} + onDismiss={toggleActive} + /> + ) : null; + + return ( +
+ + + + {toastMarkup} + + +
+ ); +} + +export default withPolarisExample(ToastWithActionExample); diff --git a/polaris.shopify.com/src/pages/examples/top-bar-with-all-of-its-elements.tsx b/polaris.shopify.com/src/pages/examples/top-bar-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/top-bar-with-all-of-its-elements.tsx rename to polaris.shopify.com/src/pages/examples/top-bar-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/top-bar-themed-with-color-scheme.tsx b/polaris.shopify.com/src/pages/examples/top-bar-with-color-scheme.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/top-bar-themed-with-color-scheme.tsx rename to polaris.shopify.com/src/pages/examples/top-bar-with-color-scheme.tsx diff --git a/polaris.shopify.com/src/pages/examples/video-thumbnail-basic.tsx b/polaris.shopify.com/src/pages/examples/video-thumbnail-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/video-thumbnail-basic.tsx rename to polaris.shopify.com/src/pages/examples/video-thumbnail-default.tsx diff --git a/polaris.shopify.com/src/pages/examples/visually-hidden-heading.tsx b/polaris.shopify.com/src/pages/examples/visually-hidden-default.tsx similarity index 100% rename from polaris.shopify.com/src/pages/examples/visually-hidden-heading.tsx rename to polaris.shopify.com/src/pages/examples/visually-hidden-default.tsx diff --git a/polaris.shopify.com/src/scripts/migrate-content.mjs b/polaris.shopify.com/src/scripts/migrate-content.mjs new file mode 100644 index 00000000000..e9d8a738ceb --- /dev/null +++ b/polaris.shopify.com/src/scripts/migrate-content.mjs @@ -0,0 +1,60 @@ +import fs from "fs"; +import path from "path"; +import { fileURLToPath } from "url"; +import glob from "glob"; +import { parseMarkdown } from "../utils/markdown.mjs"; +const __filename = fileURLToPath(import.meta.url); +const __dirname = path.dirname(__filename); + +const componentDir = path.join(__dirname, "../../content/components"); +const readmeFiles = glob.sync( + path.join(__dirname, "../../../polaris-react/src/components/*/README.md") +); + +const kebabize = (str) => { + return str + .replace(/([a-z])([A-Z])/g, "$1-$2") + .replace(/\s+/g, "-") + .toLowerCase(); +}; + +const migrateFile = async (filePath) => { + const fileTitle = kebabize(filePath.split("/").at(-2)); + const fileName = `${fileTitle}.md`; + const fileDir = path.join(componentDir, fileName); + const fileContent = fs.readFileSync(filePath, "utf-8"); + const exampleContent = fileContent + .split("---") + .filter((fileChunk) => fileChunk.startsWith("\n\n## Examples"))[0] + .replace("\n\n## Examples", ""); + + let exampleFrontMatter = "examples:"; + const examples = {}; + exampleContent.split("\n\n### ").forEach((example) => { + const title = example.split("\n")[0].trim(); + if (title === "") return; + + const kebabTitle = kebabize(title); + const exampleId = `${fileTitle}-${kebabTitle}`; + const description = example.replace(title, "").split("```")[0].trim(); + const code = example.split("```jsx").at(-1).replace("```", "").trim(); + + exampleFrontMatter += `\n - fileName: ${exampleId}.tsx\n title: ${title}`; + if (description) { + exampleFrontMatter += `\n description: ${description}`; + } + examples[`${exampleId}.tsx`] = `${code}`; + }); + + const contentNoExample = fileContent + .replace(exampleContent, "") + .replace("---\n\n## Examples", "") + .replace("\nomitAppProvider: true", "") + .replace("\n---", `\n${exampleFrontMatter}\n---`); + + fs.writeFileSync(fileDir, contentNoExample); +}; + +const migrateFiles = readmeFiles.map((filePath) => migrateFile(filePath)); + +await Promise.all(migrateFiles);