panelui-native 0.6.0 → 0.9.0

package/src/components/separator/index.tsx

@@ -0,0 +1,97 @@
+/**
+ * Separator — a rule between content.
+ *
+ * React Native has no `<hr>` and no border shorthand that survives a flex row,
+ * so a separator here is a view with a size on one axis and a stretch on the
+ * other. That is why orientation is a prop rather than something the layout
+ * infers: the component has to know which axis carries the thickness.
+ *
+ * ```tsx
+ * <Separator />
+ * <Separator orientation="vertical" />
+ * ```
+ *
+ * A vertical separator takes its length from the parent, so the parent needs a
+ * height — inside a `flex-row` with `items-stretch`, or with an explicit `h-*`
+ * on either the row or the separator itself. Without one it measures zero and
+ * nothing draws.
+ */
+import { forwardRef } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+
+const separatorVariants = tv({
+  base: 'bg-border',
+  variants: {
+    orientation: {
+      horizontal: 'w-full',
+      vertical: 'h-full',
+    },
+    variant: {
+      thin: '',
+      thick: '',
+    },
+  },
+  compoundVariants: [
+    // Thickness is on whichever axis is *not* the length, so it cannot be
+    // expressed by the orientation and variant classes independently.
+    { orientation: 'horizontal', variant: 'thin', class: 'h-px' },
+    { orientation: 'horizontal', variant: 'thick', class: 'h-1' },
+    { orientation: 'vertical', variant: 'thin', class: 'w-px' },
+    { orientation: 'vertical', variant: 'thick', class: 'w-1' },
+  ],
+  defaultVariants: {
+    orientation: 'horizontal',
+    variant: 'thin',
+  },
+});
+
+export interface SeparatorProps
+  extends ViewProps,
+    VariantProps<typeof separatorVariants> {
+  className?: string;
+  /**
+   * Thickness in pixels, overriding the variant. Sets the height of a
+   * horizontal separator and the width of a vertical one.
+   */
+  thickness?: number;
+  /**
+   * Whether the separator is only visual. A decorative separator is skipped by
+   * screen readers; set false when the split itself carries meaning — between
+   * two groups of menu items, say — and it is announced instead.
+   */
+  decorative?: boolean;
+}
+
+export const Separator = forwardRef<View, SeparatorProps>(
+  (
+    {
+      className,
+      orientation = 'horizontal',
+      variant,
+      thickness,
+      decorative = true,
+      style,
+      ...props
+    },
+    ref
+  ) => (
+    <View
+      ref={ref}
+      // `role` rather than `accessibilityRole` — React Native's older role list
+      // has no separator, the ARIA-aligned one does.
+      role={decorative ? 'none' : 'separator'}
+      accessible={!decorative}
+      aria-orientation={decorative ? undefined : orientation}
+      className={separatorVariants({ orientation, variant, className })}
+      style={
+        thickness !== undefined
+          ? [orientation === 'horizontal' ? { height: thickness } : { width: thickness }, style]
+          : style
+      }
+      {...props}
+    />
+  )
+);
+
+Separator.displayName = 'Separator';

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
@@ -22,7 +23,7 @@ import { StyleSheet, View, type ViewProps } from 'react-native';
 import { tv, type VariantProps } from 'tailwind-variants';
 
 const surfaceVariants = tv({
-  base: 'overflow-hidden rounded-3xl p-4',
+  base: 'overflow-hidden rounded-3xl',
   variants: {
     variant: {
       default: 'bg-surface',
@@ -30,9 +31,22 @@ const surfaceVariants = tv({
       tertiary: 'bg-surface-tertiary',
       transparent: 'bg-transparent',
     },
+    padding: {
+      none: '',
+      sm: 'p-2.5',
+      default: 'p-4',
+      lg: 'p-6',
+    },
+    bordered: {
+      true: 'border border-border',
+    },
+    elevated: {
+      true: 'shadow-sm',
+    },
   },
   defaultVariants: {
     variant: 'default',
+    padding: 'default',
   },
 });
 
@@ -40,17 +54,30 @@ export interface SurfaceProps
   extends ViewProps,
     VariantProps<typeof surfaceVariants> {
   className?: string;
+  /**
+   * A hairline border. A surface the same colour as what it sits on needs one
+   * to read as a distinct plane rather than dissolving into the background.
+   */
+  bordered?: boolean;
+  /**
+   * A soft shadow lifting the surface off the page. Off by default because a
+   * nested surface reads its depth from its fill, not from a shadow it would
+   * only cast onto its parent.
+   */
+  elevated?: boolean;
+  /** Inner spacing. `none` is for a surface wrapping a bled image or a chart. */
+  padding?: 'none' | 'sm' | 'default' | 'lg';
 }
 
 export const Surface = forwardRef<View, SurfaceProps>(
-  ({ className, variant, style, ...props }, ref) => (
+  ({ className, variant, padding, bordered, elevated, style, ...props }, ref) => (
     <View
       ref={ref}
       // `borderCurve` has no Tailwind equivalent. On iOS it gives the
       // continuous (squircle) corner Apple uses, which is visibly smoother
       // than a circular arc at this radius; Android ignores it.
       style={[styles.root, style]}
-      className={surfaceVariants({ variant, className })}
+      className={surfaceVariants({ variant, padding, bordered, elevated, className })}
       {...props}
     />
   )

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: