Merge pull request #665 from universal-ember/copilot/update-docs-portal-clarity

Clarify Portal CSS selector support and PortalTargets defaults

Author: NullVoxPopuli

docs-app/app/templates/5-floaty-bits/portal-targets.gjs.md

@@ -1,6 +1,20 @@
 # PortalTargets
 
-The portal targets are stable element references that can be nested over and over again to get around layering issues. 
+The portal targets are stable element references that can be nested over and over again to get around layering issues.
+
+**`<PortalTargets />` renders three hardcoded default portal targets in the DOM:**
+- `popover` - for popover elements
+- `tooltip` - for tooltip elements
+- `modal` - for modal dialogs
+
+These render as three `<div>` elements with `data-portal-name` attributes:
+```html
+<div data-portal-name="ember-primitives__portal-targets__popover"></div>
+<div data-portal-name="ember-primitives__portal-targets__tooltip"></div>
+<div data-portal-name="ember-primitives__portal-targets__modal"></div>
+```
+
+You can reference these defaults by passing their names to `<Portal @to="popover">`, `<Portal @to="tooltip">`, or `<Portal @to="modal">`.
 
 For example, given a z-index order like 
  - `1` popover

docs-app/app/templates/5-floaty-bits/portal.gjs.md

@@ -4,6 +4,8 @@ A `<Portal>` allows teleporting elements to another place in the DOM tree. This
 
 `<Portal>` must be combined with `<PortalTargets>`, or your own portal targets that match the requirements of portalling.  Additionally, a `<Portal>` will render in to the nearest `<PortalTargets>` it can find, allowing for UI layering, e.g.: Modals have their own `<PortalTargets>` so they can have their own tooltips and popovers.  _For use with popovers_, this portalling can be a way to support [popover](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/popover) on older browsers. But there are many other use cases outside of popovers as well.
 
+**The `@to` argument accepts any valid CSS selector** (like `[data-portal-target]`, `.my-class`, `#my-id`), a PortalTarget name (like `popover`, `tooltip`, or `modal`), or an Element object.
+
 <h2 visually-hidden>Usage</h2>
 
 The following example demonstrates Portal-nesting: