migration guide for Primer::DropdownMenuComponent to Primer::Beta::Dropdown

.changeset/modern-frogs-eat.md

@@ -0,0 +1,5 @@
+---
+'@primer/view-components': patch
+---
+
+Add a migration guide for moving from Primer::DropdownMenuComponent to Primer::Beta::Dropdown

docs/content/guides/primer_dropdown_menu_component.md

@@ -0,0 +1,54 @@
+---
+title: Moving Away From `Primer::DropdownMenuComponent`
+---
+
+This guide will show you how to upgrade from the now deprecated
+[`Primer::DropdownMenuComponent`](https://primer.style/view-components/components/dropdownmenu)
+to the latest [`Primer::Alpha::Dropdown`](https://primer.style/view-components/components/alpha/dropdown)
+component.
+
+## Arguments
+
+The following arguments for the component initializer have changed between the deprecated and newer versions
+of the Primer Dropdown.
+
+| From `Primer::DropdownMenuComponent` | To `Primer::Alpha::Dropdown` | Notes |
+|--------------------------------------|------------------------------|-------|
+| `direction` | n/a          | Moved to `menu` slot, below                                |
+| `scheme`    | n/a          | Moved to `menu` slot, below                                |
+| `header`    | n/a          | Moved to `menu` slot, below                                |
+| n/a         | `overlay`    | Color of the menu overlay: `:default`, `:dark`, or `:none` |
+| n/a         | `with_caret` | Whether or not a caret should be displayed on the button   |
+
+The remaining arguments have stayed the same.
+
+Please see the following documentation for complete descriptions and examples.
+
+* [Deprecated `Primer::DropdownMenuComponent`](https://primer.style/view-components/components/dropdownmenu)
+* [Updated `Primer::Alpha::Dropdown` component](https://primer.style/view-components/components/alpha/dropdown)
+* [`Primer::Alpha::Dropdown` Lookbook examples](https://primer.style/view-components/lookbook/inspect/primer/alpha/dropdown/default)
+
+## Slot Names
+
+The following slots have changed with the newer Primer Dropdown.
+
+| From `Primer::DropdownMenuComponent` | To `Primer::Alpha::Dropdown` | Notes |
+|--------------------------------------|------------------------------|-------|
+| n/a | `menu`   | Required context menu for the dropdown. See the "Arguments for `menu` slot" section, below |
+| n/a | `button` | The [`Primer::Beta::Button`](https://primer.style/view-components/components/beta/button) to display for the dropdown action |
+
+The remaining slot names have stayed the same.
+
+### Arguments for `menu` slot
+
+The following arguments are available with the `menu` named slot in Primer Dropdown.
+
+| Argument    | Description |
+|-------------|-------------|
+| `as`               | when `as` is `:list`, wraps the menu in a `<ul>` with a `<li>` for each item |
+| `direction`        | relative position to show dropdown, when button is clicked                   |
+| `header`           | optional string to display as the header                                     |
+| `scheme`           | pass `:dark` for dark mode theming                                           |
+| `system_arguments` | [System arguments](https://primer.style/view-components/system-arguments)    |
+
+[&larr; Back to migration guides](https://primer.style/view-components/migration)

docs/content/migration.md

@@ -28,3 +28,4 @@ components.
 | Deprecated Component | Replacement Component | Guide |
 |----------------------|-----------------------|-------|
 | [`Primer::ButtonComponent`](https://primer.style/view-components/components/button) | [`Primer::Beta::Button`](https://primer.style/view-components/components/beta/button) | [Upgrade to Primer::Beta::Button](https://primer.style/view-components/guides/primer_button_component) |
+| [`Primer::DropdownMenuComponent`](https://primer.style/view-components/components/dropdownmenu) | [`Primer::Alpha::Dropdown`](https://primer.style/view-components/components/alpha/dropdown) | [Upgrade to Primer::Alpha::Dropdown](https://primer.style/view-components/guides/primer_dropdown_menu_component) |

docs/src/@primer/gatsby-theme-doctocat/nav.yml

@@ -51,8 +51,6 @@
     url: "/components/alpha/dialog"
   - title: Dropdown
     url: "/components/alpha/dropdown"
-  - title: DropdownMenu
-    url: "/components/dropdownmenu"
   - title: Flash
     url: "/components/beta/flash"
   - title: Heading
@@ -119,6 +117,20 @@
     url: "/components/alpha/underlinenav"
   - title: UnderlinePanels
     url: "/components/alpha/underlinepanels"
+- title: Deprecated Components
+  children:
+  - title: BlankslateComponent
+    url: "/components/blankslate"
+  - title: BoxComponent
+    url: "/components/box"
+  - title: ButtonComponent
+    url: "/components/button"
+  - title: DropdownMenuComponent
+    url: "/components/dropdownmenu"
+  - title: IconButton
+    url: "/components/iconbutton"
+  - title: Tooltip
+    url: "/components/tooltip"
 - title: Architecture decisions
   children:
   - title: Developing and publishing client-side behaviours

lib/primer/deprecations.yml

@@ -5,47 +5,60 @@
 # See 'docs/contributors/deprecations.md' for information on configuration options.
 
 deprecations:
-  - component: "Primer::LabelComponent"
-    autocorrect: true
-    replacement: "Primer::Beta::Label"
-  - component: "Primer::LinkComponent"
-    autocorrect: true
-    replacement: "Primer::Beta::Link"
   - component: "Primer::Alpha::AutoComplete"
     autocorrect: true
     replacement: "Primer::Beta::AutoComplete"
+
   - component: "Primer::Alpha::AutoComplete::Item"
     autocorrect: true
     replacement: "Primer::Beta::AutoComplete::Item"
+
   - component: "Primer::BlankslateComponent"
     autocorrect: true
     replacement: "Primer::Beta::Blankslate"
+
   - component: "Primer::BoxComponent"
     autocorrect: true
     replacement: "Primer::Box"
+
+  - component: "Primer::ButtonComponent"
+    autocorrect: false
+    replacement: "Primer::Beta::Button"
+    guide: "https://primer.style/view-components/guides/primer_button_component"
+
   - component: "Primer::DropdownMenuComponent"
     autocorrect: false
     replacement: "Primer::Beta::Dropdown"
-    guide: "https://primer.style/view-components/migration"
+    guide: "https://primer.style/view-components/guides/primer_dropdown_menu_component"
+
   - component: "Primer::Dropdown"
     autocorrect: true
     replacement: "Primer::Alpha::Dropdown"
+
   - component: "Primer::Dropdown::Menu"
     autocorrect: true
     replacement: "Primer::Alpha::Dropdown::Menu"
+
   - component: "Primer::Dropdown::Menu::Item"
     autocorrect: true
     replacement: "Primer::Alpha::Dropdown::Menu::Item"
+
   - component: "Primer::IconButton"
     autocorrect: true
     replacement: "Primer::Beta::IconButton"
-  - component: "Primer::Tooltip"
+
+  - component: "Primer::LabelComponent"
     autocorrect: true
-    replacement: "Primer::Alpha::Tooltip"
+    replacement: "Primer::Beta::Label"
+
+  - component: "Primer::LinkComponent"
+    autocorrect: true
+    replacement: "Primer::Beta::Link"
+
   - component: "Primer::PopoverComponent"
     autocorrect: true
     replacement: "Primer::Beta::Popover"
-  - component: "Primer::ButtonComponent"
-    autocorrect: false
-    replacement: "Primer::Beta::Button"
-    guide: "https://primer.style/view-components/guides/primer_button_component"
+
+  - component: "Primer::Tooltip"
+    autocorrect: true
+    replacement: "Primer::Alpha::Tooltip"