@leta-io/components 0.2.0 → 0.4.0

package/README.md

@@ -25,6 +25,42 @@ attribute. Import `@leta-io/design-tokens/dark-elevation.css` **after** the base
 tokens — dark shadows need a hairline ring to read against a near-black surface,
 and load order decides the winner.
 
+## Overlays
+
+`Popover`, `MenuPanel`, `MenuDivider`, `MenuFlyout` and `DialogOverlay` are the
+same overlay primitives the LETA platform uses, published since 0.3.0 so you
+don't have to rebuild them. Use them rather than hand-rolling a popover — they
+carry behaviour that is easy to get wrong and hard to notice:
+
+- **One popover open at a time**, platform-wide — opening one closes the last.
+- **Escape closes only the topmost overlay**, then the next press closes the one
+  beneath it.
+- **Focus returns to the trigger** when a popover closes.
+- **A closing popover stops blocking clicks immediately**, not when its exit
+  animation ends — so a stalled animation can never leave an invisible layer
+  swallowing every click on the page.
+- **`MenuFlyout`** opens a cascading submenu beside a menu row without closing
+  the parent menu.
+
+```tsx
+import { Popover, MenuPanel, DialogOverlay } from '@leta-io/components';
+
+<Popover anchorRect={rect} onClose={close} placement="bottom-end">
+  <MenuPanel width={220}>{/* DesktopMenuOptions rows */}</MenuPanel>
+</Popover>
+
+<DialogOverlay onClose={close}>
+  {({ close }) => <ModalDialog onCancel={close} /* … */ />}
+</DialogOverlay>
+```
+
+**Stacking.** `DialogOverlay`'s `tier` is the scrim's z-index (the panel sits
+one above), defaulting to `DIALOG_OVERLAY_DEFAULT_TIER`. A dialog opened from
+*inside* another overlay — a drawer, say — must pass a tier above it, or it
+renders underneath. Keep a named tier map in your app rather than scattering bare
+numbers; the design system deliberately doesn't ship one, because it can't know
+how your surfaces stack.
+
 ## Peer dependencies
 
 React 18 or 19. `leaflet` and `lottie-web` are required only if you use the map