panelui-native 0.13.0 → 0.16.0

package/src/components/typography/index.tsx

@@ -1,14 +1,32 @@
 /**
- * Typography — semantic text presets.
+ * Typography — semantic text presets, and the marks that go on them.
  *
  * 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.
+ *
+ * ```tsx
+ * <Typography type="h2">Billing</Typography>
+ * <Typography>Your plan renews on the 1st.</Typography>
+ * <Typography underline>Terms of service</Typography>
+ * ```
+ *
+ * A preset sets size, weight and tracking together; the marks — `underline`,
+ * `italic`, `strike` — and `weight`, `align` and `transform` layer on top of
+ * whichever preset is in force. They are props rather than class names because
+ * the point of this component is that a screen never has to know which
+ * utilities add up to "a bolded lead paragraph".
+ *
+ * React Native draws no list markers and has no blockquote, so
+ * `Typography.List` and `Typography.Blockquote` build both out of a row and a
+ * rule — which is exactly the kind of thing this component exists to stop
+ * people rebuilding per screen.
  */
-import { forwardRef } from 'react';
+import { Children, forwardRef, type ReactNode } from 'react';
 import { View, type Text as RNText, type ViewProps } from 'react-native';
 import { tv, type VariantProps } from 'tailwind-variants';
 import { Text, type TextProps } from '../../primitives/text';
+import { cn } from '../../utils/cn';
 
 const typographyVariants = tv({
   base: 'text-foreground',
@@ -20,11 +38,43 @@ const typographyVariants = tv({
       h4: 'text-xl font-semibold',
       h5: 'text-lg font-semibold',
       h6: 'text-base font-semibold',
+      /** The sentence under a heading, set larger and quieter than body. */
+      lead: 'text-xl font-normal text-muted-foreground',
       body: 'text-base font-normal',
       'body-sm': 'text-sm font-normal',
       'body-xs': 'text-xs font-normal',
+      /** Body, one step up — for a number or a name that carries the row. */
+      large: 'text-lg font-semibold',
+      /** Body, one step down and tighter — captions, footnotes, meta. */
+      small: 'text-sm font-medium leading-none',
+      blockquote: 'text-base font-normal italic',
       code: 'font-mono text-sm text-foreground',
     },
+    weight: {
+      normal: 'font-normal',
+      medium: 'font-medium',
+      semibold: 'font-semibold',
+      bold: 'font-bold',
+    },
+    align: {
+      left: 'text-left',
+      center: 'text-center',
+      right: 'text-right',
+    },
+    transform: {
+      uppercase: 'uppercase',
+      lowercase: 'lowercase',
+      capitalize: 'capitalize',
+    },
+    underline: {
+      true: 'underline',
+    },
+    italic: {
+      true: 'italic',
+    },
+    strike: {
+      true: 'line-through',
+    },
     muted: {
       true: 'text-muted-foreground',
     },
@@ -38,16 +88,38 @@ export type TypographyType = NonNullable<
   VariantProps<typeof typographyVariants>['type']
 >;
 
+export type TypographyWeight = NonNullable<
+  VariantProps<typeof typographyVariants>['weight']
+>;
+
 export interface TypographyProps
   extends Omit<TextProps, 'size' | 'weight'>,
     VariantProps<typeof typographyVariants> {
   className?: string;
+  /**
+   * Overrides the weight the preset sets. This is the one to reach for when a
+   * paragraph needs a bolded run and a heading would be wrong.
+   */
+  weight?: TypographyWeight;
+  /** Underlines the text — a link, a defined term, a signature line. */
+  underline?: boolean;
+  /** Slants the text. */
+  italic?: boolean;
+  /** Strikes the text through: an old price, a completed task. */
+  strike?: boolean;
+  /** Horizontal alignment within whatever the text is laid out in. */
+  align?: 'left' | 'center' | 'right';
+  /** Case, applied for display without changing the string underneath. */
+  transform?: 'uppercase' | 'lowercase' | 'capitalize';
 }
 
 /** Heading levels, for `Typography.Heading`. */
 type HeadingType = Extract<TypographyType, 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'>;
 /** Body sizes, for `Typography.Paragraph`. */
-type ParagraphType = Extract<TypographyType, 'body' | 'body-sm' | 'body-xs'>;
+type ParagraphType = Extract<
+  TypographyType,
+  'body' | 'body-sm' | 'body-xs' | 'lead' | 'large' | 'small'
+>;
 
 /** Maps a heading preset to its accessibility heading level. */
 const HEADING_LEVEL: Record<HeadingType, number> = {
@@ -60,8 +132,25 @@ const HEADING_LEVEL: Record<HeadingType, number> = {
 };
 
 const TypographyRoot = forwardRef<RNText, TypographyProps>(
-  ({ className, type, muted, ...props }, ref) => (
-    <Text ref={ref} className={typographyVariants({ type, muted, className })} {...props} />
+  (
+    { className, type, muted, weight, align, transform, underline, italic, strike, ...props },
+    ref
+  ) => (
+    <Text
+      ref={ref}
+      className={typographyVariants({
+        type,
+        muted,
+        weight,
+        align,
+        transform,
+        underline,
+        italic,
+        strike,
+        className,
+      })}
+      {...props}
+    />
   )
 );
 TypographyRoot.displayName = 'Typography';
@@ -72,12 +161,25 @@ export interface TypographyHeadingProps extends Omit<TypographyProps, 'type'> {
 
 /** Heading text, wired up with the matching accessibility heading level. */
 const TypographyHeading = forwardRef<RNText, TypographyHeadingProps>(
-  ({ className, type = 'h2', muted, ...props }, ref) => (
+  (
+    { className, type = 'h2', muted, weight, align, transform, underline, italic, strike, ...props },
+    ref
+  ) => (
     <Text
       ref={ref}
       accessibilityRole="header"
       aria-level={HEADING_LEVEL[type]}
-      className={typographyVariants({ type, muted, className })}
+      className={typographyVariants({
+        type,
+        muted,
+        weight,
+        align,
+        transform,
+        underline,
+        italic,
+        strike,
+        className,
+      })}
       {...props}
     />
   )
@@ -89,8 +191,25 @@ export interface TypographyParagraphProps extends Omit<TypographyProps, 'type'>
 }
 
 const TypographyParagraph = forwardRef<RNText, TypographyParagraphProps>(
-  ({ className, type = 'body', muted, ...props }, ref) => (
-    <Text ref={ref} className={typographyVariants({ type, muted, className })} {...props} />
+  (
+    { className, type = 'body', muted, weight, align, transform, underline, italic, strike, ...props },
+    ref
+  ) => (
+    <Text
+      ref={ref}
+      className={typographyVariants({
+        type,
+        muted,
+        weight,
+        align,
+        transform,
+        underline,
+        italic,
+        strike,
+        className,
+      })}
+      {...props}
+    />
   )
 );
 TypographyParagraph.displayName = 'Typography.Paragraph';
@@ -106,7 +225,7 @@ const TypographyCode = forwardRef<View, TypographyCodeProps & Pick<ViewProps, 't
     <View
       ref={ref}
       testID={testID}
-      className={`self-start rounded-md bg-muted px-1.5 py-1 ${containerClassName ?? ''}`}
+      className={cn('self-start rounded-md bg-muted px-1.5 py-1', containerClassName)}
     >
       <Text className={typographyVariants({ type: 'code', muted, className })} {...props} />
     </View>
@@ -114,8 +233,110 @@ const TypographyCode = forwardRef<View, TypographyCodeProps & Pick<ViewProps, 't
 );
 TypographyCode.displayName = 'Typography.Code';
 
+export interface TypographyBlockquoteProps extends Omit<TypographyProps, 'type'> {
+  /** Classes for the row that carries the rule. */
+  containerClassName?: string;
+}
+
+/**
+ * A quotation, marked by a rule down its leading edge.
+ *
+ * The rule uses `border-s`, so it moves to the right-hand side under a
+ * right-to-left `Direction` without the quote having to know.
+ */
+const TypographyBlockquote = forwardRef<View, TypographyBlockquoteProps>(
+  ({ className, containerClassName, muted, weight, align, transform, underline, italic = true, strike, children, ...props }, ref) => (
+    <View ref={ref} className={cn('border-s-2 border-border ps-4', containerClassName)}>
+      <Text
+        className={typographyVariants({
+          type: 'blockquote',
+          muted,
+          weight,
+          align,
+          transform,
+          underline,
+          italic,
+          strike,
+          className,
+        })}
+        {...props}
+      >
+        {children}
+      </Text>
+    </View>
+  )
+);
+TypographyBlockquote.displayName = 'Typography.Blockquote';
+
+export interface TypographyListProps extends ViewProps {
+  className?: string;
+  /** Numbered rather than bulleted. The numbers are drawn, not counted by CSS. */
+  ordered?: boolean;
+  children?: ReactNode;
+}
+
+/**
+ * A bulleted or numbered list.
+ *
+ * React Native has no list markers at all, so each row is a marker and a text
+ * block side by side. The marker is drawn here rather than in the item, because
+ * only the list knows whether it is a bullet or a number — and only the list
+ * knows which number.
+ */
+const TypographyList = forwardRef<View, TypographyListProps>(
+  ({ className, ordered = false, children, ...props }, ref) => (
+    <View ref={ref} accessibilityRole="list" className={cn('gap-2', className)} {...props}>
+      {Children.map(children, (child, index) => (
+        <View className="w-full flex-row gap-2">
+          {ordered ? (
+            <Text className="text-base text-muted-foreground">{index + 1}.</Text>
+          ) : (
+            // A dot rather than "•": the character's size and baseline vary by
+            // platform font, and a view does not.
+            <View className="mt-2.5 size-1.5 shrink-0 rounded-full bg-muted-foreground" />
+          )}
+          <View className="flex-1">{child}</View>
+        </View>
+      ))}
+    </View>
+  )
+);
+TypographyList.displayName = 'Typography.List';
+
+export interface TypographyListItemProps extends Omit<TypographyProps, 'type'> {
+  type?: ParagraphType;
+}
+
+/** One line of a list. The marker beside it belongs to the list. */
+const TypographyListItem = forwardRef<RNText, TypographyListItemProps>(
+  (
+    { className, type = 'body', muted, weight, align, transform, underline, italic, strike, ...props },
+    ref
+  ) => (
+    <Text
+      ref={ref}
+      className={typographyVariants({
+        type,
+        muted,
+        weight,
+        align,
+        transform,
+        underline,
+        italic,
+        strike,
+        className,
+      })}
+      {...props}
+    />
+  )
+);
+TypographyListItem.displayName = 'Typography.ListItem';
+
 export const Typography = Object.assign(TypographyRoot, {
   Heading: TypographyHeading,
   Paragraph: TypographyParagraph,
   Code: TypographyCode,
+  Blockquote: TypographyBlockquote,
+  List: TypographyList,
+  ListItem: TypographyListItem,
 });

package/src/hooks/index.ts

@@ -17,9 +17,15 @@ export {
 export { useKeyboard, type UseKeyboardResult } from './use-keyboard';
 export {
   useKeyboardAvoidance,
+  type KeyboardAvoidanceMode,
   type UseKeyboardAvoidanceOptions,
   type UseKeyboardAvoidanceResult,
 } from './use-keyboard-avoidance';
+export {
+  useRevealProgress,
+  type UseRevealProgressOptions,
+  type UseRevealProgressResult,
+} from './use-reveal-progress';
 export {
   useScrollSections,
   type UseScrollSectionsOptions,

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

@@ -1,11 +1,24 @@
 /**
- * useKeyboardAvoidance — lift an element just clear of the software keyboard.
+ * useKeyboardAvoidance — keep an element 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.
+ * This works from the element's own position instead.
+ *
+ * Two modes, because "get out of the keyboard's way" and "ride the keyboard"
+ * are different jobs:
+ *
+ * - **`lift`** (default) — for a field sitting in the page's flow. The element
+ *   is measured every frame while the keyboard is up and moved by exactly the
+ *   current overlap, so it follows the scroll: scroll it clear and the lift
+ *   decays to nothing, scroll it back under and the lift returns. Measuring
+ *   once and holding the result is what leaves a field hanging out of its own
+ *   slot the moment the page moves underneath it.
+ * - **`dock`** — for an absolutely-positioned composer, toolbar or search bar
+ *   pinned near the bottom edge. There is nothing to measure: the element
+ *   simply travels with the keyboard, less whatever bottom inset it is already
+ *   sitting above.
  *
  * ## Install the keyboard controller
  *
@@ -31,19 +44,34 @@
  * </Animated.View>
  * ```
  */
-import { useCallback, useEffect } from 'react';
+import { useCallback, useEffect, useState } from 'react';
 import { useWindowDimensions, type LayoutChangeEvent, type View } from 'react-native';
 import {
   measure,
+  runOnJS,
   useAnimatedKeyboard,
   useAnimatedReaction,
   useAnimatedRef,
   useAnimatedStyle,
+  useFrameCallback,
   useSharedValue,
+  withTiming,
   type AnimatedRef,
   type SharedValue,
 } from 'react-native-reanimated';
 
+/** How long a lifted element takes to settle back after it stops being active. */
+const SETTLE_DURATION = 200;
+
+/**
+ * Movement below this is dropped. The element's measured position already
+ * includes the translation applied on the previous frame, so the loop reads
+ * its own output — a dead band keeps sub-pixel rounding from making it hum.
+ */
+const EPSILON = 0.5;
+
+export type KeyboardAvoidanceMode = 'lift' | 'dock';
+
 export interface UseKeyboardAvoidanceOptions {
   /** Set false to leave the element where it is. */
   enabled?: boolean;
@@ -56,14 +84,26 @@ export interface UseKeyboardAvoidanceOptions {
    * is tapped, and they all arrive at the same place on top of each other.
    */
   active?: boolean;
-  /** Gap to keep between the element's bottom edge and the keyboard. */
+  /**
+   * `lift` moves an in-flow element by its overlap with the keyboard and
+   * tracks it as the page scrolls. `dock` travels with the keyboard outright,
+   * for an element already pinned to the bottom edge.
+   */
+  mode?: KeyboardAvoidanceMode;
+  /** Gap to keep between the element's bottom edge and the keyboard. `lift` only. */
   offset?: number;
+  /**
+   * How far above the bottom edge the element already sits — usually the safe
+   * area inset it is offset by. Subtracted from the travel, since the keyboard
+   * covers that strip too. `dock` only.
+   */
+  bottomInset?: 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. */
+  /** Attach to the same element, so a re-layout at rest cannot leave it offset. */
   onLayout: (event: LayoutChangeEvent) => void;
   /** Apply to the same element. */
   animatedStyle: ReturnType<typeof useAnimatedStyle>;
@@ -110,96 +150,102 @@ export function hasKeyboardController(): boolean {
 export function useKeyboardAvoidance({
   enabled = true,
   active = true,
+  mode = 'lift',
   offset = 16,
+  bottomInset = 0,
 }: 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);
+  /** The translation currently applied, in pixels. Zero or negative. */
+  const translation = useSharedValue(0);
 
-  // `active` is a plain prop and the reaction below is a worklet, so it is
-  // mirrored rather than closed over — written in an effect, because touching
-  // a shared value during render is a Reanimated strict-mode violation.
+  // `active` is a plain prop and the worklets below cannot read props, so it is
+  // mirrored — written in an effect, because touching a shared value during
+  // render is a Reanimated strict-mode violation.
   const isActive = useSharedValue(active && enabled);
   useEffect(() => {
     isActive.value = active && enabled;
   }, [active, enabled, isActive]);
 
   /*
-   * The resting position is taken the moment this element becomes the one that
-   * should move, on the UI thread, rather than once at layout time.
+   * The whole of `lift` is this callback, and it runs only while the element is
+   * the active one *and* the keyboard is up — see the reaction below.
    *
-   * Measuring at layout is wrong in two ways that both show up as "avoidance
-   * does nothing". A field inside an overlay is laid out before the overlay
-   * knows where it goes — it is parked off-screen at that point, so the stored
-   * position is a large negative number that is nonetheless non-zero, and the
-   * arithmetic below happily concludes there is no overlap. And a field that
-   * has scrolled since it was laid out is measured where it used to be.
+   * The element is re-measured every frame rather than once, because every
+   * interesting thing that moves it happens after the keyboard opens: the page
+   * scrolls, a sheet settles, content above it grows. A position captured at
+   * the moment of focus is right for exactly one frame, and the element spends
+   * the rest of the time holding an offset that belongs to where it used to be.
    *
-   * Keying off "active and the keyboard is up" rather than off the keyboard
-   * alone matters for the second field you tap: moving straight from one field
-   * to another never closes the keyboard, so there is no opening to react to,
-   * and a hook watching only the keyboard would never measure it.
-   *
-   * At the instant it becomes active the element has no translation applied,
-   * so what is measured then is the honest resting position.
+   * What is measured already includes the translation applied on the previous
+   * frame, so that is subtracted back out to recover the honest resting edge.
+   * Without it the callback would chase its own output down the screen.
+   */
+  const track = useFrameCallback(() => {
+    'worklet';
+    const keyboardHeight = Math.abs(rawHeight.value);
+    if (keyboardHeight === 0) return;
+
+    const frame = measure(ref);
+    if (!frame || frame.height <= 0) return;
+
+    const restingBottom = frame.pageY + frame.height - translation.value;
+    const keyboardTop = screenHeight - keyboardHeight;
+    const overlap = restingBottom + offset - keyboardTop;
+    const next = overlap > 0 ? -overlap : 0;
+
+    if (Math.abs(next - translation.value) > EPSILON) translation.value = next;
+  }, false);
+
+  /*
+   * Tracking is switched on the transition rather than left running, so a
+   * screen full of fields costs nothing until one of them is being typed into.
+   * `setActive` lives on the JS side, hence the hop.
    */
+  const [tracking, setTracking] = useState(false);
   useAnimatedReaction(
     () => isActive.value && Math.abs(rawHeight.value) > 0,
-    (shouldLift, wasLifting) => {
-      if (shouldLift === wasLifting) return;
-
-      if (!shouldLift) {
-        // Forget it, so the next time round measures wherever the element has
-        // got to in the meantime.
-        restingBottom.value = 0;
-        return;
-      }
-
-      const frame = measure(ref);
-      if (frame && frame.height > 0 && frame.pageY >= 0) {
-        restingBottom.value = frame.pageY + frame.height;
+    (shouldTrack, wasTracking) => {
+      if (shouldTrack === wasTracking) return;
+      runOnJS(setTracking)(shouldTrack);
+
+      // Moving straight from one field to another never closes the keyboard,
+      // so the field being left has nothing to follow back down — it is sent
+      // home explicitly, or it stays hanging where the keyboard left it.
+      if (!shouldTrack && translation.value !== 0) {
+        translation.value = withTiming(0, { duration: SETTLE_DURATION });
       }
     }
   );
 
-  const seed = useCallback(() => {
-    // Skipped only when a position is already known and the keyboard is up —
-    // the element is lifted then, and this would store the lifted position as
-    // the resting one. With no position yet there is no translation to undo,
-    // so measuring is safe whatever the keyboard is doing.
-    if (restingBottom.value !== 0 && Math.abs(rawHeight.value) > 0) return;
-
-    ref.current?.measureInWindow((_x, y, _width, height) => {
-      if (height > 0 && y >= 0) restingBottom.value = y + height;
-    });
-  }, [ref, rawHeight, restingBottom]);
+  const { setActive } = track;
+  useEffect(() => {
+    setActive(tracking && mode === 'lift');
+    return () => setActive(false);
+  }, [tracking, mode, setActive]);
 
   const onLayout = useCallback(
     (_event: LayoutChangeEvent) => {
-      // Covers the case the reaction above cannot: a keyboard that is already
-      // up when this element mounts, where there is no transition to react to.
-      // measureInWindow is only meaningful once the view is attached and
-      // positioned, which is a frame later than onLayout on both platforms.
-      requestAnimationFrame(seed);
+      // A layout pass while the element is at rest means its slot moved for
+      // some reason other than the keyboard. Anything left over from the last
+      // lift belongs to the old slot.
+      if (!tracking && translation.value !== 0) translation.value = 0;
     },
-    [seed]
+    [tracking, translation]
   );
 
   const animatedStyle = useAnimatedStyle(() => {
-    // Both sources are normalised to a positive height here.
-    const keyboardHeight = Math.abs(rawHeight.value);
-
-    if (!isActive.value || keyboardHeight === 0 || restingBottom.value === 0) {
-      return { transform: [{ translateY: 0 }] };
+    if (mode === 'dock') {
+      if (!isActive.value) return { transform: [{ translateY: 0 }] };
+      // Both sources are normalised to a positive height here.
+      const keyboardHeight = Math.abs(rawHeight.value);
+      const travel = Math.max(keyboardHeight - bottomInset, 0);
+      return { transform: [{ translateY: -travel }] };
     }
 
-    const keyboardTop = screenHeight - keyboardHeight;
-    const overlap = restingBottom.value + offset - keyboardTop;
-
-    return { transform: [{ translateY: overlap > 0 ? -overlap : 0 }] };
+    return { transform: [{ translateY: translation.value }] };
   });
 
   return { ref, onLayout, animatedStyle };