panelui-native 0.6.0 → 0.7.0

package/src/components/shimmer/index.tsx

@@ -1,24 +1,29 @@
 /**
- * Shimmer — an animated highlight sweeping across content.
+ * Shimmer — a highlight that sweeps *through* content rather than over it.
  *
- * The React Native equivalent of shadcn-ui/ui's `shimmer` utility
- * (https://ui.shadcn.com/docs/utils/shimmer). That one is CSS:
- * `background-clip: text` with a `color-mix()` highlight. React Native has
- * neither, so the highlight is drawn as an SVG gradient band swept across an
- * overlay by Reanimated, on the UI thread.
- *
- * The visible difference: the band passes *over* the content rather than
- * being clipped to glyph shapes. On body-sized text the two read the same; on
- * very large text the web version is crisper.
+ * The content is used as a mask, and a gradient band is swept behind it on the
+ * UI thread. Because the content is the mask, the highlight is clipped to the
+ * glyph shapes: text reads as though the letters themselves are catching a
+ * light, which is the "thinking…" treatment familiar from AI chat interfaces.
  *
  * ```tsx
- * <Shimmer>
- *   <Text muted>Generating response…</Text>
- * </Shimmer>
+ * <Shimmer>Thinking…</Shimmer>
  * ```
+ *
+ * Set `as="view"` to shimmer arbitrary children (skeleton blocks, cards) — the
+ * mask is then the rendered subtree's alpha instead of a line of text.
  */
 import { useEffect, useState, type ReactNode } from 'react';
-import { View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import {
+  StyleSheet,
+  View,
+  type LayoutChangeEvent,
+  type StyleProp,
+  type TextStyle,
+  type ViewProps,
+} from 'react-native';
+import MaskedView from '@react-native-masked-view/masked-view';
+import { LinearGradient } from 'expo-linear-gradient';
 import Animated, {
   cancelAnimation,
   Easing,
@@ -28,35 +33,64 @@ import Animated, {
   withRepeat,
   withTiming,
 } from 'react-native-reanimated';
-import Svg, { Defs, LinearGradient, Rect, Stop } from 'react-native-svg';
 import { useCSSVariable } from 'uniwind';
+import { Text } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 
 export interface ShimmerProps extends ViewProps {
   className?: string;
+  /**
+   * `text` renders `children` as a single styled string and masks the sweep to
+   * the glyphs. `view` masks the sweep to whatever subtree you pass.
+   */
+  as?: 'text' | 'view';
   /** Milliseconds for one sweep. */
   duration?: number;
-  /** Sweep once instead of looping. */
+  /** Width of the highlight band, as a multiple of the content width. */
+  spread?: number;
+  /** Colour of the content at rest. Defaults to the theme's muted foreground. */
+  baseColor?: string;
+  /** Colour at the centre of the sweep. Defaults to the theme's foreground. */
+  shimmerColor?: string;
+  /** `loop` restarts from the left; `ping-pong` reverses on each pass. */
+  mode?: 'loop' | 'ping-pong';
+  /** Sweep once instead of repeating. */
   once?: boolean;
   /** Sweep right-to-left. */
   reverse?: boolean;
-  /** Width of the highlight band, as a fraction of the content width. */
-  spread?: number;
-  /** Highlight colour. Defaults to the theme's foreground. */
+  /** Set false to render the content statically without animating. */
+  enabled?: boolean;
+  /** Extra classes for the text when `as="text"`. */
+  textClassName?: string;
+  /** Extra styles for the text when `as="text"`. */
+  textStyle?: StyleProp<TextStyle>;
+  /**
+   * @deprecated Use `shimmerColor`.
+   */
   color?: string;
-  /** Peak opacity of the highlight. */
+  /**
+   * Peak opacity of the highlight.
+   * @deprecated Set `shimmerColor` to a colour with the alpha you want.
+   */
   intensity?: number;
   children?: ReactNode;
 }
 
 export function Shimmer({
   className,
+  as = 'text',
   duration = 2000,
+  spread = 2,
+  baseColor,
+  shimmerColor,
+  mode = 'loop',
   once = false,
   reverse = false,
-  spread = 0.4,
+  enabled = true,
+  textClassName,
+  textStyle,
   color,
-  intensity = 0.45,
+  intensity,
   children,
   ...props
 }: ShimmerProps) {
@@ -64,28 +98,39 @@ export function Shimmer({
   const progress = useSharedValue(0);
   const reducedMotion = useReducedMotion();
 
+  const themeMuted = useCSSVariable('--color-muted-foreground');
   const themeForeground = useCSSVariable('--color-foreground');
+
+  const base =
+    baseColor ?? (typeof themeMuted === 'string' ? themeMuted : '#a1a1aa');
   const highlight =
-    color ?? (typeof themeForeground === 'string' ? themeForeground : '#ffffff');
+    shimmerColor ??
+    color ??
+    (typeof themeForeground === 'string' ? themeForeground : '#ffffff');
+
+  // The band is wider than the content so the highlight ramps in and out
+  // instead of appearing at full strength against the edge.
+  const bandWidth = Math.max(width * spread, 1);
+  const animating = enabled && !reducedMotion && width > 0;
 
   useEffect(() => {
-    // Respect the OS setting rather than animating regardless — the same
-    // thing shadcn's utility does with prefers-reduced-motion.
-    if (reducedMotion || width === 0) return;
+    if (!animating) {
+      cancelAnimation(progress);
+      progress.value = 0;
+      return;
+    }
 
     progress.value = 0;
     progress.value = withRepeat(
       withTiming(1, { duration, easing: Easing.linear }),
       once ? 1 : -1,
-      false
+      mode === 'ping-pong'
     );
 
     return () => cancelAnimation(progress);
-  }, [duration, once, reducedMotion, width, progress]);
+  }, [animating, duration, mode, once, progress]);
 
-  const bandWidth = Math.max(width * spread, 1);
-
-  const bandStyle = useAnimatedStyle(() => {
+  const sweepStyle = useAnimatedStyle(() => {
     // Travel from fully off one edge to fully off the other.
     const from = -bandWidth;
     const to = width;
@@ -100,36 +145,84 @@ export function Shimmer({
     props.onLayout?.(event);
   };
 
+  const content =
+    as === 'text' ? (
+      <Text className={textClassName} style={[{ color: base }, textStyle]}>
+        {children}
+      </Text>
+    ) : (
+      children
+    );
+
+  // Without a measured width there is nothing to sweep across, and masking an
+  // unmeasured subtree just costs a layer — render the content plainly.
+  if (!animating) {
+    return (
+      <View {...props} onLayout={onLayout} className={className}>
+        {content}
+      </View>
+    );
+  }
+
+  const highlightWithAlpha =
+    intensity !== undefined ? withAlpha(highlight, intensity) : highlight;
+
   return (
-    <View
-      {...props}
-      onLayout={onLayout}
-      className={cn('overflow-hidden', className)}
-    >
-      {children}
-
-      {reducedMotion || width === 0 ? null : (
-        <Animated.View
-          pointerEvents="none"
-          style={[
-            { position: 'absolute', top: 0, bottom: 0, width: bandWidth },
-            bandStyle,
-          ]}
-        >
-          <Svg width="100%" height="100%">
-            <Defs>
-              <LinearGradient id="shimmer" x1="0" y1="0" x2="1" y2="0">
-                <Stop offset="0" stopColor={highlight} stopOpacity={0} />
-                <Stop offset="0.5" stopColor={highlight} stopOpacity={intensity} />
-                <Stop offset="1" stopColor={highlight} stopOpacity={0} />
-              </LinearGradient>
-            </Defs>
-            <Rect x="0" y="0" width="100%" height="100%" fill="url(#shimmer)" />
-          </Svg>
-        </Animated.View>
-      )}
+    <View {...props} onLayout={onLayout} className={cn('overflow-hidden', className)}>
+      <MaskedView maskElement={<View>{content}</View>}>
+        {/* The mask only exposes the glyphs, so this layer is what they are
+            painted with: flat base colour, plus a moving gradient band. */}
+        <View style={{ backgroundColor: base }}>
+          <View style={{ opacity: 0 }}>{content}</View>
+          <Animated.View
+            pointerEvents="none"
+            style={[
+              StyleSheet.absoluteFill,
+              { width: bandWidth, left: 0, right: undefined },
+              sweepStyle,
+            ]}
+          >
+            <LinearGradient
+              colors={[base, highlightWithAlpha, base]}
+              locations={[0, 0.5, 1]}
+              start={{ x: 0, y: 0 }}
+              end={{ x: 1, y: 0 }}
+              style={StyleSheet.absoluteFill}
+            />
+          </Animated.View>
+        </View>
+      </MaskedView>
     </View>
   );
 }
 
 Shimmer.displayName = 'Shimmer';
+
+/** Applies an alpha to a `#rgb`/`#rrggbb`/`rgb()` colour. Supports `intensity`. */
+function withAlpha(color: string, alpha: number): string {
+  const clamped = Math.max(0, Math.min(1, alpha));
+
+  if (color.startsWith('#')) {
+    const hex = color.slice(1);
+    const full =
+      hex.length === 3
+        ? hex
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : hex.slice(0, 6);
+    const r = parseInt(full.slice(0, 2), 16);
+    const g = parseInt(full.slice(2, 4), 16);
+    const b = parseInt(full.slice(4, 6), 16);
+    if (Number.isNaN(r + g + b)) return color;
+    return `rgba(${r}, ${g}, ${b}, ${clamped})`;
+  }
+
+  const channels = color.match(/rgba?\(([^)]+)\)/)?.[1];
+  if (channels) {
+    const [r, g, b] = channels.split(',').map((part) => part.trim());
+    return `rgba(${r}, ${g}, ${b}, ${clamped})`;
+  }
+
+  return color;
+}

package/src/components/surface/index.tsx

@@ -1,8 +1,9 @@
 /**
  * Surface — an elevated container.
  *
- * Adapted from: heroui-inc/heroui-native src/components/surface/
- * (the variant ladder and the nesting model for building hierarchy).
+ * The variants form a ladder rather than a palette: each step is one level
+ * further from the background, and nesting them is how you build depth without
+ * hardcoding a colour anywhere.
  *
  * Both the fill and the corner radius follow the active theme: the variants
  * resolve to themed `--color-surface-*` tokens, and `rounded-3xl` resolves

package/src/components/switch/index.tsx

@@ -7,6 +7,7 @@ import Animated, {
   withSpring,
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
+import { getNativeUI } from '../../native';
 
 const SPRING = { damping: 18, stiffness: 250, mass: 0.5 } as const;
 
@@ -37,6 +38,16 @@ export interface SwitchProps extends VariantProps<typeof switchVariants> {
   value: boolean;
   onValueChange?: (value: boolean) => void;
   disabled?: boolean;
+  /**
+   * Render the platform's own switch instead of this one. Requires the
+   * optional `@expo/ui` package; without it this prop does nothing.
+   *
+   * **Theme tokens do not apply** — the platform draws the control, so
+   * `className` and `size` are ignored.
+   */
+  native?: boolean;
+  /** Text label drawn beside the control. Native mode only. */
+  label?: string;
 }
 
 /**
@@ -44,8 +55,9 @@ export interface SwitchProps extends VariantProps<typeof switchVariants> {
  * UI thread; toggling never re-renders beyond the value change itself.
  */
 export const Switch = forwardRef<View, SwitchProps>(
-  ({ className, value, onValueChange, disabled, size = 'md' }, ref) => {
+  ({ className, value, onValueChange, disabled, size = 'md', native, label }, ref) => {
     const progress = useSharedValue(value ? 1 : 0);
+    const nativeUI = native ? getNativeUI() : null;
     const slots = switchVariants({ size, disabled: !!disabled });
 
     useEffect(() => {
@@ -62,6 +74,20 @@ export const Switch = forwardRef<View, SwitchProps>(
       opacity: progress.value,
     }));
 
+    if (nativeUI) {
+      const { Host, Switch: NativeSwitch } = nativeUI;
+      return (
+        <Host matchContents>
+          <NativeSwitch
+            value={value}
+            onValueChange={(next: boolean) => onValueChange?.(next)}
+            label={label}
+            disabled={disabled}
+          />
+        </Host>
+      );
+    }
+
     return (
       <Pressable
         ref={ref}

package/src/components/toast/index.tsx

@@ -1,10 +1,10 @@
 /**
  * Toast — transient notification.
  *
- * Adapted from: heroui-inc/heroui-native src/components/toast/
- * (the three usage patterns — string, config object, custom component — the
- * Title / Description / Action / Close anatomy, placement, and swipe-to-
- * dismiss). Styled with Coss UI tokens and PanelUI's Alert status palette.
+ * Three ways to raise one, because the right amount of ceremony differs: a
+ * bare string, a config object with a title, description and action, or a
+ * custom component when none of that fits. The anatomy underneath is the same
+ * in all three.
  *
  * The viewport is mounted for you by PanelUIProvider; `useToast()` works
  * anywhere below it.
@@ -71,8 +71,7 @@ const STACK_SCALE_STEP = 0.97;
 const EDGE_INSET = 16;
 
 /*
- * Entering/exiting animations, from heroui-inc/heroui-native
- * src/components/toast/toast.animation.ts.
+ * Entering and exiting animations.
  *
  * `mass(3)` is doing the important work: a heavy spring settles without the
  * visible overshoot a default-mass one gives. `withInitialValues` keeps
@@ -285,7 +284,7 @@ export const Toast = Object.assign(ToastRoot, {
  *
  * Swiping is vertical and direction-aware: dragging toward the screen edge the
  * toast came from dismisses it, dragging the other way rubber-bands against a
- * hard limit. Matches heroui-native's toast.animation.ts.
+ * hard limit.
  */
 function ToastSlot({
   item,
@@ -376,7 +375,7 @@ function ToastSlot({
    * Stack position plus the gesture transform.
    *
    * The whole deck takes the *newest* toast's height so the cards behind read
-   * as a uniform stack rather than a ragged pile — matching heroui-native.
+   * as a uniform stack rather than a ragged pile.
    */
   const stackStyle = useAnimatedStyle(() => {
     // Fall back to this toast's own height until the front one is measured.

package/src/components/typography/index.tsx

@@ -1,9 +1,9 @@
 /**
  * Typography — semantic text presets.
  *
- * Adapted from: heroui-inc/heroui-native (Typography `type` scale and the
- * Heading / Paragraph / Code compound parts), built on PanelUI's Text
- * primitive so every preset keeps `className` passthrough and theme colours.
+ * The type scale in one place, so headings stay consistent instead of being
+ * rebuilt out of size and weight classes at each call site. Built on the Text
+ * primitive, so every preset keeps `className` passthrough and theme colours.
  */
 import { forwardRef } from 'react';
 import { View, type Text as RNText, type ViewProps } from 'react-native';

package/src/hooks/index.ts

@@ -15,5 +15,10 @@ export {
   type UseBreakpointResult,
 } from './use-breakpoint';
 export { useKeyboard, type UseKeyboardResult } from './use-keyboard';
+export {
+  useKeyboardAvoidance,
+  type UseKeyboardAvoidanceOptions,
+  type UseKeyboardAvoidanceResult,
+} from './use-keyboard-avoidance';
 export { useDebouncedValue } from './use-debounced-value';
 export { usePrevious } from './use-previous';

package/src/hooks/use-breakpoint.ts

@@ -16,8 +16,8 @@ export interface UseBreakpointResult {
 }
 
 /**
- * Responsive state from the window size — the React Native answer to
- * coss.com/ui's `useMediaQuery`, which has no equivalent here.
+ * Responsive state from the window size — the React Native answer to a media
+ * query, which has no equivalent here.
  *
  * For styling, prefer Uniwind's responsive class prefixes (`md:flex-row`).
  * Reach for this when the *behaviour* changes, not just the look — rendering

package/src/hooks/use-copy-to-clipboard.ts

@@ -15,8 +15,6 @@ export interface UseCopyToClipboardResult {
 /**
  * Copy text to the clipboard, with a temporary "copied" state.
  *
- * Mirrors coss.com/ui's `useCopyToClipboard`.
- *
  * Requires `expo-clipboard`, which is an optional peer dependency — React
  * Native removed `Clipboard` from core, and pulling in a required native
  * module for one hook would cost every consumer who never calls it:

package/src/hooks/use-keyboard-avoidance.ts

@@ -0,0 +1,140 @@
+/**
+ * useKeyboardAvoidance — lift an element just clear of the software keyboard.
+ *
+ * `KeyboardAvoidingView` shifts or pads an entire subtree by the full keyboard
+ * height regardless of where the element actually sits, which over-scrolls
+ * short forms and does nothing useful for an element already above the fold.
+ * This measures the element and moves it by exactly the overlap — and not at
+ * all when there is none.
+ *
+ * ## Install the keyboard controller
+ *
+ * ```sh
+ * npx expo install react-native-keyboard-controller
+ * ```
+ *
+ * It is an optional peer, but on Android it is close to required. Reanimated's
+ * own `useAnimatedKeyboard` — the fallback used when the controller is absent —
+ * is deprecated in Reanimated 4, and merely *calling* it switches Android out
+ * of `adjustResize` into manual inset handling for the whole app. That is a
+ * global side effect from a local hook, and it is why keyboard avoidance built
+ * on it tends to work on iOS and break on Android.
+ *
+ * With the controller installed, wrap your app in its `KeyboardProvider` —
+ * `PanelUIProvider` does this for you when the package is present.
+ *
+ * ```tsx
+ * const { ref, onLayout, animatedStyle } = useKeyboardAvoidance();
+ *
+ * <Animated.View ref={ref} onLayout={onLayout} style={animatedStyle}>
+ *   <TextInput />
+ * </Animated.View>
+ * ```
+ */
+import { useCallback } from 'react';
+import { useWindowDimensions, type LayoutChangeEvent, type View } from 'react-native';
+import {
+  useAnimatedKeyboard,
+  useAnimatedRef,
+  useAnimatedStyle,
+  useSharedValue,
+  type AnimatedRef,
+  type SharedValue,
+} from 'react-native-reanimated';
+
+export interface UseKeyboardAvoidanceOptions {
+  /** Set false to leave the element where it is. */
+  enabled?: boolean;
+  /** Gap to keep between the element's bottom edge and the keyboard. */
+  offset?: number;
+}
+
+export interface UseKeyboardAvoidanceResult {
+  /** Attach to the element that should stay visible. */
+  ref: AnimatedRef<View>;
+  /** Attach to the same element — it is how the resting position is measured. */
+  onLayout: (event: LayoutChangeEvent) => void;
+  /** Apply to the same element. */
+  animatedStyle: ReturnType<typeof useAnimatedStyle>;
+}
+
+type KeyboardHeightHook = () => SharedValue<number>;
+
+/**
+ * Resolved once, at module load, so the hook below always calls the same
+ * underlying hook — swapping between them per render would break the rules of
+ * hooks.
+ */
+const useKeyboardHeight: KeyboardHeightHook = (() => {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const controller = require('react-native-keyboard-controller');
+    if (typeof controller?.useReanimatedKeyboardAnimation === 'function') {
+      return () => {
+        // The controller reports height as a negative offset, matching the
+        // translation you would apply. Normalise it to a positive height so
+        // the arithmetic below reads the same either way.
+        const { height } = controller.useReanimatedKeyboardAnimation();
+        return height as SharedValue<number>;
+      };
+    }
+  } catch {
+    // Not installed — fall through.
+  }
+
+  return () => useAnimatedKeyboard().height;
+})();
+
+/** True when the keyboard controller is driving this, rather than the fallback. */
+export function hasKeyboardController(): boolean {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return typeof require('react-native-keyboard-controller')
+      ?.useReanimatedKeyboardAnimation === 'function';
+  } catch {
+    return false;
+  }
+}
+
+export function useKeyboardAvoidance({
+  enabled = true,
+  offset = 16,
+}: UseKeyboardAvoidanceOptions = {}): UseKeyboardAvoidanceResult {
+  const ref = useAnimatedRef<View>();
+  const rawHeight = useKeyboardHeight();
+  const { height: screenHeight } = useWindowDimensions();
+
+  /** Window-space bottom edge of the element with no translation applied. */
+  const restingBottom = useSharedValue(0);
+
+  const measure = useCallback(() => {
+    ref.current?.measureInWindow((_x, y, _width, height) => {
+      if (height > 0) restingBottom.value = y + height;
+    });
+  }, [ref, restingBottom]);
+
+  const onLayout = useCallback(
+    (_event: LayoutChangeEvent) => {
+      // measureInWindow is only meaningful once the view is attached and
+      // positioned, which is a frame later than onLayout on both platforms.
+      requestAnimationFrame(measure);
+    },
+    [measure]
+  );
+
+  const animatedStyle = useAnimatedStyle(() => {
+    // Both sources are normalised to a positive height here.
+    const keyboardHeight = Math.abs(rawHeight.value);
+
+    if (!enabled || keyboardHeight === 0 || restingBottom.value === 0) {
+      return { transform: [{ translateY: 0 }] };
+    }
+
+    const keyboardTop = screenHeight - keyboardHeight;
+    const overlap = restingBottom.value + offset - keyboardTop;
+
+    return { transform: [{ translateY: overlap > 0 ? -overlap : 0 }] };
+  });
+
+  return { ref, onLayout, animatedStyle };
+}

package/src/icons/index.tsx

@@ -2,10 +2,10 @@
  * Icon set.
  *
  * Two families live here:
- * - Stroked 24×24 icons (Lucide geometry, as used by shadcn-ui/ui) for chrome
- *   such as chevrons and the close button.
- * - Filled 16×16 status icons for Alert and Toast indicators.
- *   Adapted from: heroui-inc/heroui-native src/components/alert/{default,success,warning}-icon.tsx
+ * - Stroked 24×24 icons on Lucide geometry, for chrome such as chevrons and
+ *   the close button.
+ * - Filled 16×16 status icons for Alert and Toast indicators, which read
+ *   better small than a stroked equivalent would.
  *
  * Every icon resolves its colour in the same order: an explicit `color` prop,
  * then the colour inherited from an enclosing `IconColorProvider`, then its

package/src/index.ts

@@ -17,11 +17,18 @@ export {
 // Primitives
 export { Portal, PortalHost, PortalProvider } from './primitives/portal';
 export { Text, type TextProps } from './primitives/text';
+export {
+  KeyboardAvoider,
+  type KeyboardAvoiderProps,
+} from './primitives/keyboard-avoider';
 export {
   AnimatedPressable,
   type AnimatedPressableProps,
 } from './primitives/animated-pressable';
 
+// Native UI bridge
+export { hasNativeUI } from './native';
+
 // Components
 export {
   Accordion,
@@ -83,7 +90,32 @@ export {
   type InputGroupInputProps,
   type InputGroupDecoratorProps,
 } from './components/input-group';
+export {
+  Item,
+  type ItemProps,
+  type ItemGroupProps,
+  type ItemSeparatorProps,
+  type ItemMediaProps,
+  type ItemContentProps,
+  type ItemTitleProps,
+  type ItemDescriptionProps,
+  type ItemActionsProps,
+  type ItemHeaderProps,
+  type ItemFooterProps,
+} from './components/item';
 export { Label, type LabelProps, type LabelTextProps } from './components/label';
+export {
+  Message,
+  type MessageProps,
+  type MessageGroupProps,
+  type MessageAvatarProps,
+  type MessageContentProps,
+  type MessageHeaderProps,
+  type MessageBubbleProps,
+  type MessageBubbleContentProps,
+  type MessageFooterProps,
+  type MessageActionsProps,
+} from './components/message';
 export { Progress, type ProgressProps } from './components/progress';
 export {
   RadioGroup,