@devalok/shilp-sutra 0.40.1 → 0.42.0

package/make-kit/components/input.md

@@ -0,0 +1,154 @@
+# Input
+
+Single-line text entry. Use instead of `<input type="text" | "email" | "url" | "tel" | "search" | "password">`.
+
+```tsx
+import { Input } from '@devalok/shilp-sutra/ui/input'
+```
+
+## When to use
+
+- Any single-line text capture: email, URL, search, name, password, phone.
+- Multi-line input? Use `<Textarea>`.
+- Number-only with steppers? Use `<NumberInput>`.
+- One-time-code / PIN entry? Use `<InputOTP>`.
+- Searchable list with selection? Use `<Combobox>` or `<Autocomplete>`.
+
+Wrap in a `<FormField>` for automatic a11y wiring (state, `aria-describedby`, `aria-invalid`, `aria-required`).
+
+## Sizes
+
+| Size | Pixel height | When |
+|---|---|---|
+| `xs` | 28 | Toolbar / inline filters. |
+| `sm` | 32 | Dense forms. |
+| `md` (default) | 40 | Standard. |
+| `lg` | 48 | Marketing / spacious layouts. |
+
+All sizes use 14 px text — sizes scale height + padding, not font.
+
+## States
+
+| State | Visual | Use |
+|---|---|---|
+| `default` (default) | Subtle border. | Resting. |
+| `error` | Red border + `aria-invalid="true"`. | Validation failure. |
+| `warning` | Amber border. | Soft caution (caps lock on, weak password). |
+| `success` | Green border. | Inline confirmation. |
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `size` | `'xs'\|'sm'\|'md'\|'lg'` | Default `md`. Excludes the HTML native `size` attribute. |
+| `state` | `'default'\|'error'\|'warning'\|'success'` | Inherits from `<FormField>` context if present. |
+| `startSection` | `ReactNode` | Leading slot — icon (React element) or label string. |
+| `endSection` | `ReactNode` | Trailing slot — icon or label. |
+| `startSectionType` | `'icon'\|'label'` | Auto-inferred from content type. Override only when needed. |
+| `endSectionType` | `'icon'\|'label'` | Auto-inferred. |
+| `startSectionClickable` | `boolean` | Enables pointer events on the section (e.g. clear button in slot). |
+| `endSectionClickable` | `boolean` | Same for trailing slot. |
+| `wrapperClassName` | `string` | Classes on the wrapper div (border, bg, ring live here). |
+| `className` | `string` | Classes on the raw `<input>` element (transparent — text only). |
+
+Plus all standard HTML input attributes except the native `size` (renamed to mean visual sizing).
+
+## Section type inference
+
+| Content | Renders as |
+|---|---|
+| React element (`<Icon icon={IconMail} />`) | `'icon'` — fixed-width centered cell. |
+| String (`"https://"`, `".00"`) | `'label'` — tinted bg + border separator. |
+
+Override via `startSectionType` / `endSectionType` when the inference is wrong.
+
+## Examples
+
+**Standard, with leading icon:**
+```tsx
+<Input
+  type="email"
+  placeholder="you@example.com"
+  startSection={<Icon icon={IconMail} />}
+/>
+```
+
+**URL prefix (label section):**
+```tsx
+<Input
+  startSection="https://"
+  placeholder="example.com"
+/>
+```
+
+**Currency with prefix icon + suffix label:**
+```tsx
+<Input
+  startSection={<Icon icon={IconCurrencyDollar} />}
+  endSection=".00"
+  placeholder="0"
+  inputMode="decimal"
+/>
+```
+
+**Clearable search (clickable trailing slot):**
+```tsx
+<Input
+  placeholder="Search projects"
+  startSection={<Icon icon={IconSearch} />}
+  endSection={
+    <button type="button" onClick={() => setValue('')} aria-label="Clear">
+      <Icon icon={IconX} />
+    </button>
+  }
+  endSectionClickable
+  value={value}
+  onChange={(e) => setValue(e.target.value)}
+/>
+```
+
+**Inside a FormField (auto-wired a11y):**
+```tsx
+<FormField state="error">
+  <Label htmlFor="email" required>Email</Label>
+  <Input id="email" type="email" />
+  <FormHelperText>Enter a valid work email.</FormHelperText>
+</FormField>
+```
+
+The Input picks up `state="error"`, `aria-describedby` (linked to FormHelperText), `aria-invalid`, and `aria-required` from FormField context automatically.
+
+**Password with reveal toggle:**
+```tsx
+const [visible, setVisible] = useState(false)
+
+<Input
+  type={visible ? 'text' : 'password'}
+  placeholder="Password"
+  endSection={
+    <button type="button" onClick={() => setVisible((v) => !v)} aria-label={visible ? 'Hide password' : 'Show password'}>
+      <Icon icon={visible ? IconEyeOff : IconEye} />
+    </button>
+  }
+  endSectionClickable
+/>
+```
+
+## Composability
+
+- **FormField:** Inside a `<FormField>`, Input auto-reads `state`, `aria-describedby`, `aria-invalid`, `aria-required` from context. Explicit props override.
+- **IconProvider:** Icons in `startSection` / `endSection` are auto-sized via the input's `size`. Don't pass `size` on the nested `<Icon>`.
+- **Container-first architecture:** Border, background, and focus ring live on the wrapper div, not the input element. Style overrides go through `wrapperClassName`, not `className`. The raw `<input>` is transparent.
+
+See `foundations/color.md` for state-color tokens, `foundations/icons.md` for the IconProvider cascade.
+
+## Rules
+
+- Pair every Input with a `<Label htmlFor="x" />` and matching `<Input id="x" />`. FormField does NOT auto-wire labels.
+- Use `wrapperClassName` for border / bg / ring overrides. `className` only changes the raw input text styling.
+- Don't pass `size` on `<Icon>` inside a section — IconProvider sets it.
+- Don't use the HTML native `size` attribute — it's excluded. Use CSS width or the size prop.
+- For interactive sections (clear button, password toggle), set `startSectionClickable` / `endSectionClickable`. Without it, the slot is `pointer-events-none`.
+- For status / validation, set `state` — it sets `aria-invalid` automatically when `state="error"`.
+- Don't use the removed `startIcon` / `endIcon` props — they were removed in 0.38. Use `startSection` / `endSection`.
+- Prefer FormField wrapping for any input with a label + helper — manual a11y wiring is error-prone.

package/make-kit/components/overview.md

@@ -0,0 +1,308 @@
+# Components — catalog & decision trees
+
+Catalog of every major component. Use this file to pick the right component before reaching for raw HTML. Per-component deep guides live alongside this file.
+
+## Decision tree — actions
+
+```
+User wants to commit / cancel / submit?
+  → primary CTA (1 per region)  → <Button variant="solid" color="accent">
+  → secondary action            → <Button variant="soft"> (NOT outline — see preference)
+  → tertiary / dismissive       → <Button variant="ghost">
+  → destructive action          → <Button variant="solid" color="error">
+  → link-styled action          → <Button variant="link">
+
+Action has a side-menu / overflow?
+  → <SplitButton> — primary + adjacent dropdown trigger.
+
+Action is icon-only?
+  → <IconButton> — same as Button, square aspect, aria-label required.
+
+Group of related actions?
+  → <ButtonGroup> — attached or not. Propagates disabled / size.
+```
+
+## Decision tree — input
+
+```
+Single-line text?
+  → <Input> — type="text"/"email"/"password"/"number"/"tel"/"url"/"search"
+  → For search specifically: <SearchInput> (has clear button + icon)
+  → For OTP code: <InputOTP>
+
+Multi-line text?
+  → <Textarea>
+
+Pick one from a list?
+  → static list ≤7 items     → <Select>
+  → static list >7 items     → <Combobox> (searchable)
+  → async / large list       → <Autocomplete>
+  → enum of 2–4 options      → <SegmentedControl> (always-visible) or <Tabs> (if scoping a section)
+
+Pick many?
+  → list with checkboxes     → <Checkbox> per item
+  → compact pills            → <ToggleGroup type="multiple">
+  → searchable               → <Combobox multiple>
+
+Boolean?
+  → <Switch> (settings-style on/off) — instant action
+  → <Checkbox> (form field) — confirmed-on-submit
+  → <Toggle> (button-like toggled state)
+
+Range / scalar?
+  → <Slider> (single or multi-thumb range)
+  → <NumberInput> (precise number with steppers)
+
+Date / time?
+  → <DatePicker> (single date)
+  → <DateRangePicker> (range)
+  → <DateTimePicker> (date + time)
+
+Color?
+  → <ColorInput> (popover swatch + manual hex)
+  → <ColorSwatch> (display-only)
+
+File?
+  → <FileUpload> (drag-drop + click)
+```
+
+## Decision tree — feedback
+
+```
+Permanent inline message?
+  → <Alert>     — page-level notice (info / success / warning / error)
+  → <Banner>    — full-bleed page banner (system status, announcements)
+  → <InfoBlock> — within a form / card (helper context)
+
+Status of an item?
+  → <Badge>          — pill label (status / tag)
+  → <StatusBadge>    — colored dot + label (discriminated union: status="online"/"away"/...)
+  → <StatusDot>      — just the colored dot
+
+Temporary notification?
+  → toast.success / error / warning / info (imperative) — must have <Toaster /> mounted
+
+Loading / pending?
+  → <Spinner>           — generic
+  → <ProgressRing>      — determinate ring
+  → <Progress>          — linear bar
+  → <Skeleton>          — content placeholder shimmer
+  → <PageSkeletons.*>   — pre-built page-level skeletons
+  → <GlobalLoading>     — app-wide loading overlay
+
+Empty state?
+  → <EmptyState> — icon + heading + body + action
+```
+
+## Decision tree — overlays
+
+```
+Confirm a destructive action?         → <AlertDialog> or <ConfirmDialog>
+Show a form / detailed flow?          → <Dialog>  (auto fullScreen on mobile)
+Show a side panel?                    → <Sheet>   (auto bottom-drawer on mobile)
+Show a small floating popup on click? → <Popover>
+Show a small floating popup on hover? → <HoverCard>
+Show a label on hover?                → <Tooltip>
+Show a menu from a button?            → <DropdownMenu>
+Show a menu from right-click?         → <ContextMenu>
+Show a menu in a toolbar?             → <Menubar>
+Show a command palette (cmd+K)?       → <AppCommandPalette> (shell) or <CommandPalette> (composed)
+```
+
+## Decision tree — navigation
+
+```
+Top of every page?
+  → <TopBar> (shell)
+
+Side nav (product)?
+  → <AppSidebar> (shell) — collapsible, with sections, footer
+
+Tabs within a page?
+  → <Tabs>            — horizontal default
+  → <Tabs orientation="vertical"> — side-nav within a card
+
+Pages within a flow?
+  → <Stepper>         — multi-step wizard, optional clickable
+
+Breadcrumb trail?
+  → <Breadcrumb>
+
+Pagination?
+  → <Pagination>
+
+Mobile bottom nav?
+  → <BottomNavbar>
+```
+
+## Decision tree — layout
+
+```
+Page wrapper?
+  → <Container size="..."> — max-width constraints (sm / md / lg / xl / 2xl / full)
+
+Vertical / horizontal stack?
+  → <Stack direction="col|row" gap="ds-*">
+
+A card / panel?
+  → <Card> — surface-raised + shadow-raised
+  → <Card variant="..."> — tinted by color prop
+
+A grid?
+  → use native CSS grid utilities (grid grid-cols-12 gap-ds-05) — no kit primitive for this
+
+Aspect-ratio box?
+  → <AspectRatio ratio={16/9}>
+
+Divider?
+  → <Separator> (horizontal default; orientation="vertical")
+
+Collapsible section?
+  → <Collapsible> (single)
+  → <Accordion> (group, single-open or multi-open)
+```
+
+## Decision tree — data display
+
+```
+Tabular data?
+  → <Table>      — simple, hand-roll rows/cells
+  → <DataTable>  — full-featured (sort, paginate, select, filter, export, density, mobile-card)
+
+Key-value display?
+  → <StatCard>          — single big stat
+  → 4 StatCards in a row → use <Stack direction="row" gap="ds-05">
+
+Activity / event log?
+  → <ActivityFeed>      — vertical timeline with dots
+
+User avatars?
+  → <Avatar>           — single
+  → <AvatarGroup>       — stack with overflow
+
+A list of selectable members?
+  → <MemberPicker>
+
+A chart?
+  → BarChart / LineChart / AreaChart / PieChart / RadarChart / GaugeChart / Sparkline (from /ui/charts)
+
+Code?
+  → <Code> inline
+  → <MarkdownViewer> for rendered markdown
+```
+
+## Component catalog by category
+
+### Actions
+| Component | Subpath | Purpose |
+|---|---|---|
+| Button | `/ui/button` | Primary action element. |
+| IconButton | `/ui/icon-button` | Icon-only square button. |
+| ButtonGroup | `/ui/button-group` | Visually attached group. |
+| SplitButton | `/ui/split-button` | Action + dropdown. |
+| OAuthButton | `/ui/oauth-button` | Brand-aware social login button. |
+| Toggle | `/ui/toggle` | Toggled-state button. |
+| ToggleGroup | `/ui/toggle-group` | Group of toggles (single / multiple). |
+| Link | `/ui/link` | Themed anchor. |
+
+### Inputs
+| Component | Subpath |
+|---|---|
+| Input | `/ui/input` |
+| Textarea | `/ui/textarea` |
+| Select | `/ui/select` |
+| Combobox | `/ui/combobox` |
+| Autocomplete | `/ui/autocomplete` |
+| SearchInput | `/ui/search-input` |
+| NumberInput | `/ui/number-input` |
+| InputOTP | `/ui/input-otp` |
+| Checkbox | `/ui/checkbox` |
+| Radio | `/ui/radio` |
+| Switch | `/ui/switch` |
+| Slider | `/ui/slider` |
+| FileUpload | `/ui/file-upload` |
+| ColorInput | `/ui/color-input` |
+| ColorSwatch | `/ui/color-swatch` |
+| DatePicker | `/composed/date-picker` |
+| Label | `/ui/label` |
+| Form / FormField | `/ui/form` |
+| SegmentedControl | `/ui/segmented-control` |
+
+### Overlays
+| Component | Subpath |
+|---|---|
+| Dialog | `/ui/dialog` |
+| AlertDialog | `/ui/alert-dialog` |
+| Sheet | `/ui/sheet` |
+| Popover | `/ui/popover` |
+| HoverCard | `/ui/hover-card` |
+| Tooltip | `/ui/tooltip` |
+| DropdownMenu | `/ui/dropdown-menu` |
+| ContextMenu | `/ui/context-menu` |
+| Menubar | `/ui/menubar` |
+
+### Feedback
+| Component | Subpath |
+|---|---|
+| Alert | `/ui/alert` |
+| Banner | `/ui/banner` |
+| Toast / Toaster | `/ui/toast`, `/ui/toaster` |
+| Spinner | `/ui/spinner` |
+| Progress | `/ui/progress` |
+| ProgressRing | `/ui/progress-ring` |
+| Skeleton | `/ui/skeleton` |
+| Badge | `/ui/badge` |
+| StatusBadge | `/composed/status-badge` |
+| StatusDot | `/ui/status-dot` |
+| EmptyState | `/composed/empty-state` |
+
+### Layout
+| Component | Subpath |
+|---|---|
+| Container | `/ui/container` |
+| Stack | `/ui/stack` |
+| Card | `/ui/card` |
+| AspectRatio | `/ui/aspect-ratio` |
+| Separator | `/ui/separator` |
+| Accordion | `/ui/accordion` |
+| Collapsible | `/ui/collapsible` |
+
+### Navigation
+| Component | Subpath |
+|---|---|
+| Tabs | `/ui/tabs` |
+| Breadcrumb | `/ui/breadcrumb` |
+| Pagination | `/ui/pagination` |
+| Stepper | `/ui/stepper` |
+| NavigationMenu | `/ui/navigation-menu` |
+| Sidebar (AppSidebar) | `/shell/sidebar` |
+| TopBar | `/shell/top-bar` |
+| BottomNavbar | `/shell/bottom-navbar` |
+
+### Data display
+| Component | Subpath |
+|---|---|
+| Table | `/ui/table` |
+| DataTable | `/ui/data-table` |
+| StatCard | `/ui/stat-card` |
+| ActivityFeed | `/composed/activity-feed` |
+| Avatar | `/ui/avatar` |
+| AvatarGroup | `/composed/avatar-group` |
+| Text | `/ui/text` |
+| Code | `/ui/code` |
+| Charts (bar / line / area / pie / radar / gauge / sparkline) | `/ui/charts/*` |
+
+## Common props across components
+
+| Prop | Type | Where |
+|---|---|---|
+| `className` | string | All. Use sparingly. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | Button, Input, Select, Card, Alert, Badge, Tabs, Checkbox, Radio, Slider, etc. Not all sizes exist on every component. |
+| `color` | `'accent' \| 'error' \| 'success' \| 'warning' \| 'info' \| 'neutral'` | Button, Badge, Card, Tabs (subset), Alert. |
+| `variant` | varies | Button (`solid|soft|outline|ghost|link`), Card, Alert, Badge, Select, etc. |
+| `disabled` | boolean | All interactive. Propagates from ButtonGroup. |
+| `loading` | boolean | Button, IconButton, OAuthButton, async-aware components. |
+
+## Per-component guides
+
+See `components/{button|card|input|dialog|badge|select|tabs|toast|form|table|dropdown-menu|popover|text|stack|icon}.md` for prop tables, examples, and rules.

package/make-kit/components/popover.md

@@ -0,0 +1,201 @@
+# Popover
+
+Click-triggered floating panel for interactive content anchored to a trigger.
+
+```tsx
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverAnchor,
+} from '@devalok/shilp-sutra/ui/popover'
+```
+
+## When to use
+
+- Interactive panel anchored to a button: filter form, date picker, color picker, share popover.
+- A list of actions? Use `<DropdownMenu>` — keyboard model differs (arrow nav vs. Tab nav).
+- Inert hover label (tooltip)? Use `<Tooltip>`.
+- Rich hover preview (user card, link preview)? Use `<HoverCard>`.
+- Critical full-attention interaction? Use `<Dialog>`.
+
+On mobile, Popover auto-promotes to a bottom drawer when it would overflow the viewport — don't rebuild this manually.
+
+## Compound shape
+
+```
+Popover (root — open, onOpenChange, defaultOpen, modal)
+  PopoverTrigger          ← asChild around your button
+  PopoverAnchor           ← optional, decouples trigger from positioning origin
+  PopoverContent          ← portalled, accepts side/align/sideOffset
+```
+
+## Root state props (Radix passthrough)
+
+| Prop | Type | Notes |
+|---|---|---|
+| `open` | `boolean` | Controlled. |
+| `onOpenChange` | `(open: boolean) => void` | |
+| `defaultOpen` | `boolean` | Uncontrolled. |
+| `modal` | `boolean` | Default `false`. Set `true` for backdrop + focus trap (rare — usually use Dialog). |
+
+## PopoverContent positioning
+
+| Prop | Type | Notes |
+|---|---|---|
+| `side` | `'top'\|'right'\|'bottom'\|'left'` | Preferred side. Floats to opposite side if it would overflow. |
+| `align` | `'start'\|'center'\|'end'` | Alignment relative to trigger. |
+| `sideOffset` | `number` (px) | Gap between trigger and content. |
+| `collisionPadding` | `number \| { top, right, bottom, left }` | Distance from viewport edges before flipping. |
+
+All Floating-UI positioning options pass through via Radix.
+
+## Examples
+
+**Filter form:**
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="soft" startIcon={IconFilter}>Filters</Button>
+  </PopoverTrigger>
+  <PopoverContent align="start">
+    <Stack gap="ds-04">
+      <FormField>
+        <Label htmlFor="status">Status</Label>
+        <Select value={status} onValueChange={setStatus}>
+          <SelectTrigger id="status">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            <SelectItem value="all">All</SelectItem>
+            <SelectItem value="active">Active</SelectItem>
+            <SelectItem value="archived">Archived</SelectItem>
+          </SelectContent>
+        </Select>
+      </FormField>
+      <Stack direction="horizontal" gap="ds-03" justify="end">
+        <Button variant="ghost" size="sm" onClick={reset}>Clear</Button>
+        <Button size="sm" onClick={apply}>Apply</Button>
+      </Stack>
+    </Stack>
+  </PopoverContent>
+</Popover>
+```
+
+**Date picker:**
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="soft" startIcon={IconCalendar}>
+      {date ? formatDate(date) : 'Pick a date'}
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <Calendar value={date} onChange={(d) => { setDate(d); setOpen(false) }} />
+  </PopoverContent>
+</Popover>
+```
+
+**Share popover with copy link:**
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="soft" startIcon={IconShare}>Share</Button>
+  </PopoverTrigger>
+  <PopoverContent side="bottom" align="end">
+    <Stack gap="ds-03">
+      <Text variant="label-sm">Share link</Text>
+      <Stack direction="horizontal" gap="ds-02">
+        <Input value={shareUrl} readOnly className="flex-1" />
+        <IconButton
+          icon={<Icon icon={copied ? IconCheck : IconCopy} />}
+          variant="soft"
+          aria-label="Copy link"
+          onClick={() => { navigator.clipboard.writeText(shareUrl); setCopied(true) }}
+        />
+      </Stack>
+    </Stack>
+  </PopoverContent>
+</Popover>
+```
+
+**Decoupled anchor (trigger ≠ positioning origin):**
+```tsx
+<Popover>
+  <PopoverAnchor>
+    <Card>
+      <CardHeader>
+        <CardTitle>Project</CardTitle>
+        <PopoverTrigger asChild>
+          <IconButton icon={<Icon icon={IconInfo} />} variant="ghost" size="sm" aria-label="About" />
+        </PopoverTrigger>
+      </CardHeader>
+    </Card>
+  </PopoverAnchor>
+  <PopoverContent side="top">
+    Popover positions relative to the whole Card, not the small info button.
+  </PopoverContent>
+</Popover>
+```
+
+**Inside a Dialog (nested overlays work correctly):**
+```tsx
+<Dialog>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Schedule meeting</DialogTitle>
+    </DialogHeader>
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="soft">Pick a time</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <TimePicker value={time} onChange={setTime} />
+      </PopoverContent>
+    </Popover>
+  </DialogContent>
+</Dialog>
+```
+
+Popover uses `z-popover` (1400), above `z-dialog`. Nesting works without z-index fights.
+
+**Controlled with custom close behavior:**
+```tsx
+const [open, setOpen] = useState(false)
+
+<Popover open={open} onOpenChange={setOpen}>
+  <PopoverTrigger asChild>
+    <Button>Open</Button>
+  </PopoverTrigger>
+  <PopoverContent
+    onInteractOutside={(e) => {
+      if (hasUnsavedChanges) {
+        e.preventDefault()
+        confirmClose().then((ok) => ok && setOpen(false))
+      }
+    }}
+  >
+    <UnsavedForm />
+  </PopoverContent>
+</Popover>
+```
+
+## Composability
+
+- **Built on Radix Popover** — every standard Radix prop passes through.
+- **Portal rendering:** PopoverContent portals to body. CSS `overflow: hidden` / `transform` on ancestors don't clip it.
+- **z-popover (1400):** Above Dialog (`z-dialog`). Nested popovers inside dialogs stack correctly.
+- **PopoverAnchor:** Decouples the visual anchor from the interactive trigger. Useful when the trigger is small (icon button) but the popover should position relative to a larger surrounding element.
+
+See `foundations/surfaces.md` for overlay surface, `foundations/motion.md` for the spring open animation, `foundations/spacing.md` for internal popover padding.
+
+## Rules
+
+- Use Popover for interactive content (forms, pickers). Use DropdownMenu for action lists — different keyboard model.
+- `<PopoverTrigger asChild>` around any focusable element — usually a Button or IconButton.
+- Set `modal={true}` only when the popover blocks interaction with the rest of the page. Default `false` is correct for filters / pickers.
+- Set explicit `side` + `align` for predictable positioning. Defaults bottom-center, but designs often want `align="end"` for right-anchored triggers.
+- Don't use Popover for tooltips — Tooltip is for inert hover labels. Popover requires explicit click.
+- Don't nest Popover inside Popover. Use a single Popover with stepped content, or close the first before opening the second.
+- For complex form flows that need full attention, switch to Dialog. Popovers shouldn't host multi-step wizards.
+- The internal padding inside `PopoverContent` is preset — don't add wrapper divs with extra padding. Use `<Stack gap>` to space content.