@ahrowe/ui 0.15.0 → 0.16.0

package/dist/types/package/common/tilt/index.d.ts

@@ -0,0 +1,4 @@
+export { default } from './tilt';
+export * from './tilt.types';
+export { defaultTiltEasing } from './tiltMath';
+export type { TiltAxisLock } from './tiltMath';

package/dist/types/package/common/tilt/tilt.d.ts

@@ -0,0 +1,3 @@
+import { TiltHandle, TiltProps } from './tilt.types';
+declare const Tilt: import('react').ForwardRefExoticComponent<TiltProps & import('react').RefAttributes<TiltHandle>>;
+export default Tilt;

package/dist/types/package/common/tilt/tilt.types.d.ts

@@ -0,0 +1,38 @@
+import { CSSProperties, ReactNode } from 'react';
+import { SlotClassNames, SlotStyles, HtmlProps } from '../types/slots.types';
+import { TiltAxisLock } from './tiltMath';
+export type TiltTrackingMode = 'self' | 'group';
+export type TiltSlots = 'root' | 'perspective' | 'surface';
+export interface TiltHandle {
+    /** Directly drives the tilt rotation, clamped to `maxTilt`/`maxTiltX`/`maxTiltY`. For custom choreography (e.g. shuffling). */
+    setTilt: (rotateX: number, rotateY: number) => void;
+    /** Returns to flat. */
+    reset: () => void;
+}
+export interface TiltProps extends HtmlProps {
+    children?: ReactNode;
+    /** Shared clamp for both tilt axes, in degrees. @default 15 */
+    maxTilt?: number;
+    /** Overrides `maxTilt` for the X axis (tilts top/bottom edges, driven by vertical cursor position). */
+    maxTiltX?: number;
+    /** Overrides `maxTilt` for the Y axis (tilts left/right edges, driven by horizontal cursor position). */
+    maxTiltY?: number;
+    /** CSS `perspective` in px, applied to the perspective wrapper. @default 800 */
+    perspective?: number;
+    /** Easing curve applied to the normalized cursor offset (range roughly [-1, 1]) before scaling by `maxTilt`. @default defaultTiltEasing */
+    easing?: (t: number) => number;
+    /** Disables tilt on one axis entirely. @default 'none' */
+    lockAxis?: TiltAxisLock;
+    /** Cosmetic `scale()` applied together with the tilt while tracking. @default 1 */
+    scaleOnHover?: number;
+    /** `'self'` tracks the pointer over this element's own bounding box; `'group'` reads a shared pointer position from an ancestor `TiltGroup`, falling back to `'self'` if none exists. @default 'self' */
+    trackingMode?: TiltTrackingMode;
+    /** Disables tilt tracking entirely. @default false */
+    disabled?: boolean;
+    /** Fires on every applied tilt update. */
+    onTiltChange?: (rotateX: number, rotateY: number) => void;
+    className?: string;
+    style?: CSSProperties;
+    classNames?: SlotClassNames<TiltSlots>;
+    styles?: SlotStyles<TiltSlots>;
+}

package/dist/types/package/common/tilt/tiltMath.d.ts

@@ -0,0 +1,24 @@
+export type TiltAxisLock = 'x' | 'y' | 'none';
+export interface ComputeTiltOptions {
+    maxTiltX: number;
+    maxTiltY: number;
+    easing: (t: number) => number;
+    lockAxis: TiltAxisLock;
+}
+export interface TiltResult {
+    rotateX: number;
+    rotateY: number;
+}
+/**
+ * Eases faster near the edges (|t| close to 1) and flatter near the center (|t| close to 0),
+ * while staying odd-symmetric so tilt direction always matches cursor direction.
+ */
+export declare function defaultTiltEasing(t: number): number;
+/**
+ * Computes the tilt rotation for a pointer at (x, y) relative to `rect`'s top-left corner.
+ * Vertical cursor position drives rotateX (tilts top/bottom edges), horizontal drives rotateY.
+ */
+export declare function computeTilt(x: number, y: number, rect: {
+    width: number;
+    height: number;
+}, { maxTiltX, maxTiltY, easing, lockAxis }: ComputeTiltOptions): TiltResult;

package/dist/types/package/common/tiltGroup/index.d.ts

@@ -0,0 +1,3 @@
+export { default } from './tiltGroup';
+export { useTiltGroup, TiltGroupContext } from './tiltGroup';
+export * from './tiltGroup.types';

package/dist/types/package/common/tiltGroup/tiltGroup.d.ts

@@ -0,0 +1,6 @@
+import { ReactElement } from 'react';
+import { TiltGroupContextValue, TiltGroupProps } from './tiltGroup.types';
+export declare const TiltGroupContext: import('react').Context<TiltGroupContextValue | null>;
+export declare function useTiltGroup(): TiltGroupContextValue | null;
+declare function TiltGroup({ children, className, style, ...rest }: TiltGroupProps): ReactElement;
+export default TiltGroup;

package/dist/types/package/common/tiltGroup/tiltGroup.types.d.ts

@@ -0,0 +1,16 @@
+import { CSSProperties, ReactNode } from 'react';
+import { HtmlProps } from '../types/slots.types';
+export interface TiltGroupContextValue {
+    /** Last known pointer position, in coordinates relative to the group container's top-left corner. `null` once the pointer has left. */
+    pointer: {
+        x: number;
+        y: number;
+    } | null;
+    /** The group container's bounding rect, refreshed on pointer enter/move. */
+    rect: DOMRect | null;
+}
+export interface TiltGroupProps extends HtmlProps {
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+}

package/dist/types/package/index.d.ts

@@ -51,6 +51,8 @@ export { default as ErrorBoundary } from './common/errorBoundary';
 export * from './common/errorBoundary';
 export { default as Fab } from './common/fab';
 export * from './common/fab';
+export { default as Flip } from './common/flip';
+export * from './common/flip';
 export { default as FloatingMenu } from './common/floatingMenu';
 export * from './common/floatingMenu';
 export { default as IconPicker } from './common/iconPicker';
@@ -86,6 +88,8 @@ export { default as RadioGroup } from './common/radioGroup';
 export * from './common/radioGroup';
 export { default as Rating } from './common/rating';
 export * from './common/rating';
+export { default as RevealLens } from './common/revealLens';
+export * from './common/revealLens';
 export { default as Ripple } from './common/ripple';
 export * from './common/ripple';
 export { default as RoomDrawer } from './common/roomDrawer';
@@ -117,6 +121,10 @@ export * from './common/textarea';
 export { default as ThemeProvider } from './common/themeProvider';
 export * from './common/themeProvider';
 export { useTheme } from './common/themeProvider/useTheme';
+export { default as Tilt } from './common/tilt';
+export * from './common/tilt';
+export { default as TiltGroup } from './common/tiltGroup';
+export * from './common/tiltGroup';
 export { default as TimeInput } from './common/timeInput';
 export * from './common/timeInput';
 export { default as Timeline } from './common/timeline';

package/docs/CLAUDE.md

@@ -119,6 +119,7 @@ Slot keys per component are documented in each component's doc file below.
 @EmptyState.md
 @ErrorBoundary.md
 @Fab.md
+@Flip.md
 @FloatingMenu.md
 @FormValidator.md
 @FormValidatorGroup.md
@@ -139,6 +140,7 @@ Slot keys per component are documented in each component's doc file below.
 @ProgressBar.md
 @RadioGroup.md
 @Rating.md
+@RevealLens.md
 @Ripple.md
 @RoomDrawer.md
 @RoomViewer.md
@@ -154,6 +156,7 @@ Slot keys per component are documented in each component's doc file below.
 @TabHeader.md
 @Textarea.md
 @ThemeProvider.md
+@Tilt.md
 @TimeInput.md
 @Timeline.md
 @Toast.md

package/docs/Dropdown.md

@@ -56,4 +56,4 @@ const statusValidator = new FormValidator('', [Validators.required()]);
 | `useMatLabelStyle` | `boolean` | Material-style floating label |
 | `alwaysFloatLabel` | `boolean` | Keep the material label floated in the border notch even when nothing is selected, so an empty dropdown reads as blank instead of showing the label as if it were the selected value. Only applies with `useMatLabelStyle` (default) |
 
-The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view.
+The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.

package/docs/Flip.md

@@ -0,0 +1,97 @@
+# Flip
+
+**When to use:** Flip a front/back pair of content 180°, like a physical playing card. Works completely standalone (it establishes its own `perspective`), or nested inside `Tilt` (with `perspective="none"`, since `Tilt` already establishes one) for a flippable, tilting card. Use it for a reveal-the-back interaction, a card in a hand of cards, or any two-sided toggle that should feel like a physical flip rather than a cross-fade.
+
+**Import:** `import { Flip } from '@ahrowe/ui'`
+**Types:** `import type { FlipProps, FlipHandle } from '@ahrowe/ui'`
+
+```tsx
+import { useState } from 'react';
+import { Flip } from '@ahrowe/ui';
+
+// Controlled, click to flip
+const [flipped, setFlipped] = useState(false);
+
+<Flip
+  style={{ width: 220, height: 280 }}
+  flipped={flipped}
+  flipOnClick
+  onFlip={setFlipped}
+  front={<div>Click to flip</div>}
+  back={<div>Here's the back!</div>}
+/>
+```
+
+**Direction:** `flipAxis` picks which edge the flip hinges on (`'y'`, the default, hinges on the left/right edges; `'x'` hinges on the top/bottom edges). `reverse` flips the rotation sign on that same axis (+180deg vs -180deg), so the flip sweeps the opposite way without changing which edge it hinges on, useful for a hand of cards where neighboring cards should visually sweep toward each other rather than all sweeping the same direction:
+
+```tsx
+<Flip flipAxis="y" front={<Face />} back={<Back />} />              {/* sweeps left-right */}
+<Flip flipAxis="y" reverse front={<Face />} back={<Back />} />      {/* sweeps right-left */}
+<Flip flipAxis="x" front={<Face />} back={<Back />} />              {/* sweeps top-bottom */}
+<Flip flipAxis="x" reverse front={<Face />} back={<Back />} />      {/* sweeps bottom-top */}
+```
+
+**Imperative control (custom animation, e.g. a shuffle):**
+
+```tsx
+import { useRef } from 'react';
+import { Flip } from '@ahrowe/ui';
+import type { FlipHandle } from '@ahrowe/ui';
+
+const cardRef = useRef<FlipHandle>(null);
+
+<Flip ref={cardRef} style={{ width: 220, height: 280 }} front={<Face />} back={<Back />} />
+
+cardRef.current?.flip();               // toggles flip (uncontrolled instances only)
+cardRef.current?.setFlipped(true);     // explicit set (uncontrolled instances only)
+cardRef.current?.reset();              // back to unflipped (front-facing)
+```
+
+`flip()`/`setFlipped()` are no-ops (with a dev-only console warning) on a **controlled** instance (one with a `flipped` prop); update the `flipped` prop instead. `onFlip` fires only for a user-initiated flip (click or ref call), never for an externally-driven `flipped` prop change.
+
+**Composing with `Tilt`:**
+
+```tsx
+import { Tilt, Flip } from '@ahrowe/ui';
+
+<Tilt style={{ width: 220, height: 280 }}>
+  <Flip style={{ width: '100%', height: '100%' }} perspective="none" front={<Face />} back={<Back />} />
+</Tilt>
+```
+
+`Tilt` already establishes a `perspective` on its own wrapper, so pass `perspective="none"` to `Flip` when nesting it there to avoid two stacked perspective contexts. `Flip` doesn't inherit `Tilt`'s size on its own (it has no size of its own until you give it one), so size it to `100%` to fill `Tilt`'s surface.
+
+**Sizing:** `Flip` doesn't impose a size of its own — give the root an explicit size via `style`/`className` (e.g. `style={{ width: 220, height: 280 }}`) whenever `front`/`back` are sized in percentages (`width: '100%'`) and need something to size against. Left unset, `Flip` sizes itself to fit its content instead of collapsing to 0×0, taking the larger of `front`/`back`'s natural size (both faces are stacked in the same CSS grid cell, so the wider/taller one sets the size for both, even though only the front is visible at rest).
+
+**Motion:** the flip always animates over `flipDuration`, whether triggered by a click, a controlled prop change, or the ref API. Under `prefers-reduced-motion: reduce`, it flips instantly instead. `onFlipEnd` fires once the flip settles on its new face — after the transition completes normally, or synchronously under reduced motion, since no transition runs to wait for.
+
+**Keyboard accessibility:** when `flipOnClick` is set, the root gets `role="button"`, `tabIndex={0}`, and `aria-pressed` reflecting the current flip state, and Enter/Space both toggle the flip the same way a click does. None of this is applied when `flipOnClick` is `false`, since the element isn't interactive.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `front` | `ReactNode` | Front-face content (required) |
+| `back` | `ReactNode` | Back-face content (required) |
+| `flipped` | `boolean` | Controlled flip state |
+| `defaultFlipped` | `boolean` | Initial flip state when uncontrolled (default `false`) |
+| `flipOnClick` | `boolean` | Clicking toggles flip (uncontrolled) or calls `onFlip` (controlled) (default `false`) |
+| `flipAxis` | `'x' \| 'y'` | Which edge the flip hinges on (default `'y'`) |
+| `reverse` | `boolean` | Flips the rotation sign on `flipAxis`, so the sweep direction reverses (default `false`) |
+| `flipDuration` | `number` | Flip transition duration in ms (default `600`) |
+| `perspective` | `number \| 'none'` | CSS `perspective` in px on the perspective wrapper; pass `'none'` when nesting inside something that already establishes one, e.g. `Tilt` (default `800`) |
+| `disabled` | `boolean` | Disables `flipOnClick`; programmatic flips via prop or ref still work (default `false`) |
+| `onFlip` | `(flipped: boolean) => void` | Fires for a user-initiated flip (click or ref call), not fired for an externally-driven `flipped` prop change |
+| `onFlipEnd` | `(flipped: boolean) => void` | Fires once the flip transition finishes settling on the new face, for any trigger. Fires synchronously under `prefers-reduced-motion: reduce` |
+
+**`FlipHandle`** (via `ref`):
+
+| Method | Description |
+|--------|-------------|
+| `flip()` | Toggles the flip state (uncontrolled instances only) |
+| `setFlipped(value)` | Explicitly sets the flip state (uncontrolled instances only) |
+| `reset()` | Returns to unflipped (front-facing) |
+
+**Global defaults:** `Flip` adopts `ConfigProvider`, e.g. `defaultProps={{ Flip: { flipDuration: 400 } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `perspective` `surface` `front` `back`

package/docs/FloatingMenu.md

@@ -52,6 +52,8 @@ import { FloatingMenu, Align } from '@ahrowe/ui';
 
 **Slots:** `root` `trigger` `menu` `menuContainer`
 
+**Positioning:** the menu is portaled and tracks the trigger across scroll and resize, flipping above it when there's no room below. It re-measures whenever `content` changes size while open, so a menu holding a list that grows or shrinks (filtering, async loading) stays anchored to the trigger and re-evaluates whether it still needs to open upward.
+
 **Closing behaviour:** by default, clicking anywhere in `content` closes the menu — including inside a nested overlay that renders through its own portal (e.g. a `Dropdown` or another `FloatingMenu` used inside `content`), even though that overlay's DOM lives outside `content`'s own subtree. Re-clicking the trigger while open is a clean toggle: it closes the menu (unless `dontCloseOnChildClick` is set, in which case it's a no-op — the trigger owns its own open/close entirely, so it never fights with an outside-click check). Set `dontCloseOnChildClick` when `content` needs several interactions before the user is done (a multi-checkbox toggle, a color picker's slider, a calendar) — the consumer is then responsible for closing explicitly, e.g. calling `onOpenChange(false)` from the handler that reacts to a final selection.
 
 **Keyboard:** the menu is portaled to the end of the DOM, so Tab can't reach it in visual order on its own. When `content` has real focusable elements, Escape closes the menu and returns focus to the trigger; Tab past the last focusable element (or Shift+Tab past the first) closes the menu and continues focus as if it sat right after the trigger. This doesn't include auto-focusing the first element on open — content ranges from menus to live controls (e.g. `ColorPicker`'s hue slider), where grabbing focus on open would let a stray arrow-key press change a value the user never touched. A consumer that wants that (like `SplitButton` focusing its first enabled action) implements it itself.

package/docs/Input.md

@@ -29,9 +29,12 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 // Multiline (textarea)
 <Input label="Notes" multiline rows={4} value={notes} onChange={setNotes} />
 
-// Phone with mask
+// Phone — sets type="tel" and the numeric dial-pad keyboard, no formatting of its own
 <Input label="Phone" type={InputType.Phone} formValidator={phoneValidator} />
 
+// Formatted while typing, via parse — an IBAN grouped in blocks of four
+<Input label="IBAN" parse={formatIban} value={iban} onChange={setIban} />
+
 // With suffix
 <Input label="Amount" suffix="€" value={amount} onChange={setAmount} />
 
@@ -65,6 +68,24 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 
 **Mobile keyboard layout:** `Email`, `Phone`, and `Search` each set the matching `inputMode` (`email` / `tel` / `search`), so mobile browsers show the right on-screen keyboard — an `@`-and-`.com` layout for email, a numeric dial pad for phone, a "Go"/search action key for search. `Email`'s native `type` is deliberately left as `text` rather than `email`, to avoid the browser's own "please match the requested format" validation UI fighting the `formValidator`-driven error tooltip this component already shows — `inputMode="email"` alone is enough to get the correct keyboard. Pass `inputMode` directly to override the computed default for any other case.
 
+**Formatting while typing (`parse`):** `parse` runs on every change, before the value reaches `onChange` and `formValidator`, and its return value is what gets stored and rendered. That makes it the hook for keeping a field in a canonical shape as the user types, rather than fixing it up on blur or submit:
+
+```tsx
+// Uppercase, drop anything that isn't a letter or digit, group in blocks of four,
+// cap at the 34-character IBAN maximum
+const formatIban = (value: string) =>
+  value
+    .replace(/[^a-zA-Z0-9]/g, '')
+    .toUpperCase()
+    .slice(0, 34)
+    .replace(/(.{4})/g, '$1 ')
+    .trim();
+
+<Input label="IBAN" type={InputType.Iban} parse={formatIban} value={iban} onChange={setIban} />
+```
+
+The stored value is the formatted one, spaces included, so strip them before a length check or checksum (`value.replace(/\s/g, '')`). Two limits worth knowing: inserting characters in the middle of an already-formatted value can move the caret to the end, since the whole value is rewritten (append-only typing is unaffected), and `parse` can't reject a keystroke, only rewrite the result. For a fixed-width field where per-position rules and caret handling matter more (a date, a card number), drive a mask library through `customInput` instead.
+
 **Key props:**
 
 | Prop | Type | Description |
@@ -94,6 +115,8 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 | `readOnly` | `boolean` | |
 | `autoFocus` | `boolean` | |
 | `placeholder` | `string` | |
-| `parse` | `(value: string) => string` | Transform value before onChange |
+| `parse` | `(value: string) => string` | Transform the value on every change, before `onChange`/`formValidator` — also what gets rendered (see above) |
+| `isUppercase` | `boolean` | Uppercases the field's rendering (CSS only — the stored value is unchanged; use `parse` to uppercase the value itself) |
+| `customInput` | `ReactElement` | Element rendered in place of the internal `<input>`, cloned with all of Input's props. The escape hatch for a mask library; note `autoFocus` and `autoResize` stop working, since Input cannot attach its ref |
 
 **Slots:** `label` `container` `input` `suffix` `upperRightLabel` `fieldset`

package/docs/InputDropdown.md

@@ -64,4 +64,4 @@ interface InputDropdownItem {
 
 **Slots:** `root` `dropdown` `item`
 
-The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view.
+The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view. It also re-measures when its own content changes size while open, so a list that shrinks (e.g. filtered down to fewer entries) stays anchored to the trigger instead of hanging above it.

package/docs/RevealLens.md

@@ -0,0 +1,67 @@
+# RevealLens
+
+**When to use:** A two-layer reveal/magnifier effect — an `overlay` covers a `background` by default, and moving the pointer over the component uncovers the `background` in an area around the cursor. `background`/`overlay` are plain `ReactNode`s, so either can be an image, a solid colour block, or any other component (even an animated one) — swap two images on hover, reveal a crisp image over a blurred version, or magnify any custom content.
+
+**Import:** `import { RevealLens } from '@ahrowe/ui'`
+
+```tsx
+import { RevealLens } from '@ahrowe/ui';
+
+// Swap two images on hover
+<RevealLens
+  style={{ width: 480, height: 300 }}
+  background={<img src="/photo-alt.jpg" style={{ width: '100%', height: '100%', objectFit: 'cover' }} />}
+  overlay={<img src="/photo.jpg" style={{ width: '100%', height: '100%', objectFit: 'cover' }} />}
+/>
+
+// Crisp image revealed over a blurred version — a magnifying-glass effect
+<RevealLens
+  style={{ width: 480, height: 300 }}
+  background={<img src="/photo.jpg" style={{ width: '100%', height: '100%', objectFit: 'cover' }} />}
+  overlay={
+    <img
+      src="/photo.jpg"
+      style={{ width: '100%', height: '100%', objectFit: 'cover', filter: 'blur(8px)' }}
+    />
+  }
+  radius={90}
+  feather={40}
+/>
+
+// Any component as either layer
+<RevealLens
+  style={{ width: 480, height: 300 }}
+  background={<AnimatedLogo />}
+  overlay={<div style={{ background: 'var(--primary-color)' }}>Hover to reveal</div>}
+/>
+
+// Hard edge (no soft feather)
+<RevealLens background={<Crisp />} overlay={<Faded />} radius={80} feather={0} />
+
+// A fully custom CSS mask instead of the built-in circle
+<RevealLens
+  background={<Crisp />}
+  overlay={<Faded />}
+  maskImage="linear-gradient(to right, transparent, white)"
+/>
+```
+
+**Sizing:** `background` and `overlay` are stacked in the same CSS grid cell rather than given a size of their own, so give the root an explicit size via `style`/`className` (e.g. `style={{ width: 480, height: 300 }}`) whenever they're sized in percentages (`width: '100%'`, as in the examples above) and need something to size against. Left unset, `RevealLens` sizes itself to fit its content, taking the larger of `background`/`overlay`'s natural size.
+
+**Touch:** built on Pointer Events, so it works the same for mouse and touch — dragging a finger across the component moves the reveal like a magnifier. The reveal snaps back to the overlay when the pointer/touch ends or leaves.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `background` | `ReactNode` | Bottom layer, revealed around the pointer (required) |
+| `overlay` | `ReactNode` | Top layer, covers `background` by default (required) |
+| `radius` | `number` | Reveal radius in px (default `120`) |
+| `feather` | `number` | Soft edge width in px; `0` gives a hard edge (default `24`) |
+| `shape` | `'circle' \| 'custom'` | Documents the reveal shape being used (default `'circle'`); the actual mask is a circle unless `maskImage` is set |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used verbatim instead of the built-in circle gradient — the escape hatch for a non-circular reveal |
+| `disabled` | `boolean` | Disables pointer tracking — `overlay` stays fully visible (default `false`) |
+
+**Global defaults:** adopts `ConfigProvider`, e.g. `defaultProps={{ RevealLens: { radius: 150 } }}`. See [ConfigProvider.md](ConfigProvider.md).
+
+**Slots:** `root` `background` `overlay`

package/docs/Tilt.md

@@ -0,0 +1,124 @@
+# Tilt
+
+**When to use:** Wrap content that should tilt toward the cursor in 3D. Pointer position drives a `rotateX`/`rotateY` tilt that flattens out near the center and ramps up (with an eased, non-linear curve) toward the edges. Use it for clean UI polish, like a row of pricing/plan cards that each tilt independently on hover, or as a low-level primitive for custom animation, like a hand of cards that all react to one shared cursor. Compose with `Flip` for a card that both tilts and flips.
+
+**Import:** `import { Tilt, TiltGroup } from '@ahrowe/ui'`
+**Types:** `import type { TiltProps, TiltHandle, TiltGroupProps } from '@ahrowe/ui'`
+
+```tsx
+import { Tilt } from '@ahrowe/ui';
+
+// Basic hover tilt
+<Tilt style={{ width: 220, height: 280 }}>
+  <div>Hover me</div>
+</Tilt>
+
+// Limit the tilt angle, and tilt less on one axis than the other, good for a row
+// of cards that should feel subtle rather than dramatic
+<Tilt style={{ width: 180, height: 240 }} maxTilt={10} maxTiltX={4}>
+  <PlanCard />
+</Tilt>
+
+// Lock tilt to a single axis
+<Tilt style={{ width: 220, height: 280 }} lockAxis="y">
+  <div>Only tilts left/right</div>
+</Tilt>
+```
+
+**Imperative control (custom animation):**
+
+```tsx
+import { useRef } from 'react';
+import { Tilt } from '@ahrowe/ui';
+import type { TiltHandle } from '@ahrowe/ui';
+
+const tiltRef = useRef<TiltHandle>(null);
+
+<Tilt ref={tiltRef} style={{ width: 220, height: 280 }}>
+  <div>Content</div>
+</Tilt>
+
+tiltRef.current?.setTilt(8, -12); // drive rotation directly, clamped to maxTilt/maxTiltX/maxTiltY
+tiltRef.current?.reset();         // back to flat
+```
+
+**Tracking a shared cursor with `TiltGroup` (a hand of cards):**
+
+```tsx
+import { Tilt, TiltGroup } from '@ahrowe/ui';
+
+<TiltGroup style={{ position: 'relative', width: 480, height: 220 }}>
+  {cards.map((card, i) => (
+    <div key={card.id} style={{ position: 'absolute', left: '50%', transform: `rotate(${fanAngle(i)}deg)` }}>
+      <Tilt trackingMode="group">
+        <CardFace card={card} />
+      </Tilt>
+    </div>
+  ))}
+</TiltGroup>
+```
+
+By default (`trackingMode="self"`), a `Tilt` only tilts while the pointer is over its own bounding box. With `trackingMode="group"`, it instead reads the cursor position from an ancestor `TiltGroup` and reacts to it relative to *its own* rect, so a whole hand of cards responds to one shared cursor, each computing its own tilt from the same pointer position, the way light falling across a fanned hand of physical cards would. `TiltGroup` renders a single plain `div`; give it its own size/position via `style`/`className`. If `trackingMode="group"` is set with no ancestor `TiltGroup`, it falls back to `"self"` tracking and logs a one-time dev warning.
+
+**Composing with `Flip` (a tilting, flippable card):**
+
+```tsx
+import { Tilt, Flip } from '@ahrowe/ui';
+
+<Tilt style={{ width: 220, height: 280 }}>
+  <Flip style={{ width: '100%', height: '100%' }} perspective="none" front={<Face />} back={<Back />} />
+</Tilt>
+```
+
+`Flip` sizes itself to fit `front`/`back`'s content by default, which usually isn't what you want nested inside `Tilt`, so size it to `100%` to fill `Tilt`'s surface instead. See [Flip.md](Flip.md) for the rest of `Flip`'s API.
+
+**Sizing:** `Tilt` doesn't impose a size. Give the root an explicit size via `style`/`className` (e.g. `style={{ width: 220, height: 280 }}`).
+
+**Put the card's visual surface on the content, not the root:** only the `surface` slot actually receives the 3D rotation, the root just establishes position and size. A background, shadow, or border-radius set via `className`/`style` on `Tilt` itself stays flat while the content tilts inside it. Put that styling on `children` (or target the `surface` slot via `classNames`/`styles`) so the whole visible surface tilts as one:
+
+```tsx
+// Wrong: the box stays flat, only the text inside it tilts
+<Tilt className={styles.card} style={{ width: 220, height: 280 }}>Hover me</Tilt>
+
+// Right: the visual surface is on the content that actually rotates
+<Tilt style={{ width: 220, height: 280 }}>
+  <div className={styles.cardFace}>Hover me</div>
+</Tilt>
+```
+
+**Tilt tuning:** `maxTilt` (and the per-axis `maxTiltX`/`maxTiltY` overrides) clamp the rotation in degrees; the normalized cursor offset is passed through an easing curve (default export `defaultTiltEasing`) before being scaled by the clamp, so tilt stays flatter near the center and ramps up faster near the edges rather than scaling linearly. Pass your own `easing` function (`(t: number) => number`, `t` roughly in `[-1, 1]`) for a different feel.
+
+**Motion:** tilt tracking is throttled to at most one update per animation frame, and eases in smoothly on entry/leave via a JS-driven catch-up (not a CSS transition, since CSS transitions can't gracefully follow a continuously-moving target). Under `prefers-reduced-motion: reduce`, live tilt tracking is disabled entirely and the element stays flat.
+
+**Key props:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | Content that tilts |
+| `maxTilt` | `number` | Shared clamp for both axes, in degrees (default `15`) |
+| `maxTiltX` / `maxTiltY` | `number` | Per-axis override for `maxTilt` |
+| `perspective` | `number` | CSS `perspective` in px on the perspective wrapper (default `800`) |
+| `easing` | `(t: number) => number` | Easing curve applied to the normalized cursor offset (default `defaultTiltEasing`) |
+| `lockAxis` | `'x' \| 'y' \| 'none'` | Disables tilt on one axis entirely (default `'none'`) |
+| `scaleOnHover` | `number` | Cosmetic `scale()` applied together with the tilt while tracking (default `1`) |
+| `trackingMode` | `'self' \| 'group'` | `'self'` tracks this element's own bounding box; `'group'` reads a shared pointer from an ancestor `TiltGroup` (default `'self'`) |
+| `disabled` | `boolean` | Disables tilt tracking entirely (default `false`) |
+| `onTiltChange` | `(rotateX: number, rotateY: number) => void` | Fires on every applied tilt update |
+
+**`TiltHandle`** (via `ref`):
+
+| Method | Description |
+|--------|-------------|
+| `setTilt(rotateX, rotateY)` | Directly drives the tilt rotation, clamped to `maxTilt`/`maxTiltX`/`maxTiltY` |
+| `reset()` | Returns to flat |
+
+**`TiltGroupProps`:**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `children` | `ReactNode` | The `Tilt`s (and any other content) inside the tracked area |
+| `className` / `style` | | Root element; give it its own size/position |
+
+**Global defaults:** `Tilt` adopts `ConfigProvider`, e.g. `defaultProps={{ Tilt: { maxTilt: 10 } }}`. See [ConfigProvider.md](ConfigProvider.md). `TiltGroup` doesn't adopt `ConfigProvider`; it has no prop surface beyond `children`/`className`/`style`.
+
+**Slots:** `root` `perspective` `surface`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "publishConfig": {
     "access": "public"
   },