@provex/components 1.6.2 → 1.7.0-rc.20260522201545.020a3eb

package/skills/components-integration/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: components-integration
+description: Use when integrating `@provex/components` — when adding a Tooltip that needs to portal correctly, when adding a MenuSelect that survives ancestor CSS transforms, when wiring URL-synced React state via useUrlState, when rendering the standard Card page-shell, or when extending one of the package's primitives. Covers the deliberately narrow scope of the package, the theme-agnostic Chakra pattern, the transform-anchoring gotcha behind MenuSelect's existence, and which primitives have optional peer dependencies.
+---
+
+# `@provex/components` Integration
+
+A small, focused set of React UI primitives shared across Provex apps. **This is not a general-purpose component library.** It exists to plug gaps the surrounding libraries (Chakra UI, recharts, react-router-dom) leave open. The API stability bar is "we don't break our own apps" — third-party integrators are welcome, but expect occasional churn.
+
+## What's actually exported
+
+| Component / Hook | Purpose | Why it exists |
+|---|---|---|
+| `Tooltip` | Drop-in tooltip | Chakra v2's portal misbehaves on mobile and inside certain overflow contexts. Always use this, **never** Chakra's `Tooltip`. |
+| `MenuSelect` | Anchored popover select | Chakra's popover positioning breaks when an ancestor has `transform: ...`. This uses `getBoundingClientRect` + absolute positioning, no transform. |
+| `Card` | Page-shell card | Standard padding, border, surface token; pairs with `Container maxW="container.xl" px={0}` for the canonical layout. |
+| `useUrlState` (`/url-state`) | Round-trip state through query params | Needs react-router context; subpath-imported to avoid loading react-router unless used. |
+
+Source files in the repo also define `SubProviderSelector`, `MenuItem`, and a handful of layout helpers — check the root barrel for the current full set.
+
+## Tooltip — don't reach for Chakra's
+
+```tsx
+import { Tooltip } from '@provex/components'
+
+<Tooltip label="Explanation text">
+  <Button>Hover me</Button>
+</Tooltip>
+```
+
+If you see Chakra's `Tooltip` imported anywhere in the codebase, that's a bug — replace it with this one. The recharts library also exports a `Tooltip`; always alias it:
+
+```tsx
+import { Tooltip as RechartsTooltip } from 'recharts'
+```
+
+## MenuSelect — the transform gotcha
+
+`MenuSelect` exists because `triggerRef.getBoundingClientRect()` returns *post-transform* coordinates, but child positioning that uses `transform: translateY(...)` measures from the pre-transform anchor. The result is a dropdown that lands ~`trigger.y` off when an ancestor has `transform: scale(...)`, `transform: translate(...)`, or similar.
+
+Inside this component, anchoring is done via `bottom: -Npx` and absolute positioning — never `transform`. If you extend it or build something similar, follow the same rule.
+
+```tsx
+import { MenuSelect } from '@provex/components'
+
+<MenuSelect
+  options={[{ value: 'a', label: 'Alpha' }, { value: 'b', label: 'Beta' }]}
+  value={selected}
+  onChange={setSelected}
+/>
+```
+
+## Card — page-shell convention
+
+```tsx
+import { Container, Card } from '@chakra-ui/react'
+
+<Container maxW="container.xl" px={0}>
+  <Card>
+    {/* standalone Cards span the container; grid Cards take cell width */}
+  </Card>
+</Container>
+```
+
+This is the canonical Provex page-shell. Stats and Activity pages already use it; follow the same shape when adding new pages.
+
+## useUrlState — React Router required
+
+```tsx
+import { useUrlState } from '@provex/components/url-state'
+
+function FilterPanel() {
+  const [filter, setFilter] = useUrlState('filter', { defaultValue: 'all' })
+  // filter is reflected in the URL as ?filter=all
+}
+```
+
+Requires a `react-router-dom` context above it. If you're not using react-router, don't import `/url-state` — react-router won't be loaded.
+
+## Peer dependencies — which are optional
+
+```ts
+{
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "@chakra-ui/react": "^2.0.0 || ^3.0.0",    // optional
+    "react-router-dom": "^6.0.0 || ^7.0.0",     // optional
+    "viem": "^2.0.0"                            // optional
+  }
+}
+```
+
+- `react` is hard-required.
+- `@chakra-ui/react` is required only for the components that render Chakra primitives (most of them). If you don't have Chakra in your app, this package won't be useful to you.
+- `react-router-dom` is required only for `useUrlState`. Skip the subpath, skip react-router.
+- `viem` is type-level only — used in a few prop types. Won't trigger a runtime error if absent.
+
+## Chakra-version compatibility
+
+The components target Chakra v2 idioms but the peer range includes v3. Some components (notably `MenuSelect`) compose Chakra primitives that shifted between v2 and v3 — if you're on v3, expect to test these surfaces specifically. The Provex monorepo is on v2 today.
+
+## A landmine to know about: semantic-token fall-through
+
+Chakra v2's `whiteAlpha`/`blackAlpha` scales cap at `.900`. Referencing `.950` (or any other non-existent step) resolves to `transparent` at runtime, silently. If a Provex component's hover/focus state looks invisible, check the token chain first via `var(--chakra-colors-X)` in DevTools, before assuming the component is broken.
+
+## When NOT to import from this package
+
+- **You're not using Chakra** → most components render Chakra primitives and will be confusing or broken.
+- **You want a richer component library** → this package is intentionally narrow. Reach for Chakra, Radix, Mantine, etc.
+- **You want recharts wrappers** → not here. Aliasing recharts' `Tooltip` is your responsibility per-import.