panelui-native 0.22.5 → 0.25.0

package/src/components/breadcrumb/index.tsx

@@ -0,0 +1,365 @@
+/**
+ * Breadcrumb — the trail of where you are in a hierarchy.
+ *
+ * A row of links back up the tree, ending in the page you are on. The last
+ * crumb is not a link: you cannot navigate to where you already are, so it is
+ * a plain, current-marked label rather than a dead tappable target.
+ *
+ * The separators are the component's job, not yours. `Breadcrumb.List` drops a
+ * chevron between each crumb it holds, so a trail is just its items — there is
+ * no separator to forget, mis-order, or leave dangling at the end. Change the
+ * glyph once with `separator` on the root and every gap follows.
+ *
+ * ```tsx
+ * <Breadcrumb>
+ *   <Breadcrumb.List>
+ *     <Breadcrumb.Item>
+ *       <Breadcrumb.Link onPress={goHome}>Home</Breadcrumb.Link>
+ *     </Breadcrumb.Item>
+ *     <Breadcrumb.Item>
+ *       <Breadcrumb.Link onPress={goProjects}>Projects</Breadcrumb.Link>
+ *     </Breadcrumb.Item>
+ *     <Breadcrumb.Item>
+ *       <Breadcrumb.Page>PanelUI</Breadcrumb.Page>
+ *     </Breadcrumb.Item>
+ *   </Breadcrumb.List>
+ * </Breadcrumb>
+ * ```
+ *
+ * A deep trail on a narrow phone does not wrap into a paragraph: give the list
+ * a `maxItems` and it keeps the first and last crumbs, folding the middle into
+ * a single ellipsis. Hand the ellipsis an `onEllipsisPress` and it becomes the
+ * handle for a menu of the hidden steps.
+ */
+import {
+  Children,
+  createContext,
+  forwardRef,
+  isValidElement,
+  useContext,
+  type ReactNode,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+import { useCSSVariable } from 'uniwind';
+import { ChevronRightIcon, EllipsisIcon } from '../../icons';
+import {
+  AnimatedPressable,
+  type AnimatedPressableProps,
+} from '../../primitives/animated-pressable';
+import { Text, type TextProps } from '../../primitives/text';
+import { cn } from '../../utils/cn';
+
+type BreadcrumbSize = 'sm' | 'default';
+
+const crumbText = tv({
+  base: '',
+  variants: {
+    size: {
+      sm: 'text-xs',
+      default: 'text-sm',
+    },
+  },
+  defaultVariants: { size: 'default' },
+});
+
+/**
+ * Sub-parts read the density and the shared separator glyph from here, so the
+ * trail is configured once on the root rather than repeated per crumb.
+ */
+const BreadcrumbContext = createContext<{
+  size: BreadcrumbSize;
+  separator: ReactNode;
+}>({
+  size: 'default',
+  separator: null,
+});
+
+const useBreadcrumb = () => useContext(BreadcrumbContext);
+
+export interface BreadcrumbProps extends ViewProps {
+  className?: string;
+  /** Text density for every crumb. `sm` for a dense header bar. */
+  size?: BreadcrumbSize;
+  /**
+   * The glyph `Breadcrumb.List` places between crumbs. Defaults to a chevron;
+   * pass a `<Text>/</Text>`, a slash, or any node to change every gap at once.
+   */
+  separator?: ReactNode;
+  children?: ReactNode;
+}
+
+/**
+ * The trail's landmark. Labelled for assistive tech so the row is announced as
+ * "Breadcrumb" rather than an anonymous run of links.
+ */
+const BreadcrumbRoot = forwardRef<View, BreadcrumbProps>(
+  ({ className, size = 'default', separator, children, ...props }, ref) => (
+    <BreadcrumbContext.Provider value={{ size, separator: separator ?? null }}>
+      <View
+        ref={ref}
+        accessibilityLabel="Breadcrumb"
+        className={cn('w-full', className)}
+        {...props}
+      >
+        {children}
+      </View>
+    </BreadcrumbContext.Provider>
+  )
+);
+BreadcrumbRoot.displayName = 'Breadcrumb';
+
+export interface BreadcrumbListProps extends ViewProps {
+  className?: string;
+  /**
+   * Collapse the trail once it holds more than this many crumbs, so a deep
+   * path never wraps into a block of text on a narrow screen. The first
+   * `itemsBeforeCollapse` and last `itemsAfterCollapse` survive; the middle
+   * folds into a single ellipsis.
+   */
+  maxItems?: number;
+  /** How many leading crumbs to keep when collapsing. Default 1. */
+  itemsBeforeCollapse?: number;
+  /** How many trailing crumbs to keep when collapsing. Default 1. */
+  itemsAfterCollapse?: number;
+  /**
+   * Makes the collapsed ellipsis pressable — the handle for a menu listing the
+   * hidden steps. Without it the ellipsis is a static marker.
+   */
+  onEllipsisPress?: () => void;
+  children?: ReactNode;
+}
+
+/** A private marker: the slot the collapsed middle crumbs fold into. */
+const COLLAPSE = Symbol('breadcrumb-collapse');
+
+/**
+ * The crumb row. It owns the separators — one between every pair of crumbs and
+ * none at the ends — and the collapsing, so a caller only ever lists items.
+ */
+const BreadcrumbList = forwardRef<View, BreadcrumbListProps>(
+  (
+    {
+      className,
+      maxItems,
+      itemsBeforeCollapse = 1,
+      itemsAfterCollapse = 1,
+      onEllipsisPress,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    const crumbs = Children.toArray(children).filter(isValidElement);
+
+    // Fold the middle only when hiding something actually shortens the row:
+    // keeping N-1 of N crumbs plus an ellipsis saves nothing.
+    let sequence: Array<ReactNode | typeof COLLAPSE> = crumbs;
+    if (
+      maxItems !== undefined &&
+      crumbs.length > maxItems &&
+      itemsBeforeCollapse + itemsAfterCollapse < crumbs.length
+    ) {
+      const head = crumbs.slice(0, Math.max(0, itemsBeforeCollapse));
+      const tail =
+        itemsAfterCollapse > 0 ? crumbs.slice(crumbs.length - itemsAfterCollapse) : [];
+      sequence = [...head, COLLAPSE, ...tail];
+    }
+
+    return (
+      <View
+        ref={ref}
+        accessibilityRole="list"
+        className={cn('flex-row flex-wrap items-center gap-1.5', className)}
+        {...props}
+      >
+        {sequence.map((node, i) => (
+          <View key={i} className="flex-row items-center gap-1.5">
+            {i > 0 ? <BreadcrumbSeparator /> : null}
+            {node === COLLAPSE ? (
+              <BreadcrumbEllipsis onPress={onEllipsisPress} />
+            ) : (
+              node
+            )}
+          </View>
+        ))}
+      </View>
+    );
+  }
+);
+BreadcrumbList.displayName = 'Breadcrumb.List';
+
+export interface BreadcrumbItemProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/** One crumb: wraps a link or the current page. */
+const BreadcrumbItem = forwardRef<View, BreadcrumbItemProps>(
+  ({ className, children, ...props }, ref) => (
+    <View
+      ref={ref}
+      className={cn('flex-row items-center', className)}
+      {...props}
+    >
+      {children}
+    </View>
+  )
+);
+BreadcrumbItem.displayName = 'Breadcrumb.Item';
+
+export interface BreadcrumbLinkProps
+  extends Omit<AnimatedPressableProps, 'children'> {
+  className?: string;
+  /** Text style for the crumb's label. */
+  textClassName?: string;
+  children?: ReactNode;
+}
+
+/**
+ * A navigable crumb — an ancestor you can jump back to. Muted until pressed,
+ * so the current page (which is not a link) reads as the emphasised end of the
+ * trail. A string child is wrapped in the crumb text style; anything else
+ * renders as given.
+ */
+const BreadcrumbLink = forwardRef<View, BreadcrumbLinkProps>(
+  ({ className, textClassName, children, ...props }, ref) => {
+    const { size } = useBreadcrumb();
+
+    return (
+      <AnimatedPressable
+        ref={ref}
+        accessibilityRole="link"
+        pressScale={1}
+        pressOpacity={0.6}
+        className={cn('flex-row items-center', className)}
+        {...props}
+      >
+        {typeof children === 'string' ? (
+          <Text className={crumbText({ size, className: cn('text-muted-foreground', textClassName) })}>
+            {children}
+          </Text>
+        ) : (
+          children
+        )}
+      </AnimatedPressable>
+    );
+  }
+);
+BreadcrumbLink.displayName = 'Breadcrumb.Link';
+
+export interface BreadcrumbPageProps extends TextProps {
+  className?: string;
+}
+
+/**
+ * The trailing crumb: where you are now. Not a link — `aria-current="page"`
+ * marks it as the destination, and it is painted in the full foreground so the
+ * trail resolves to it.
+ */
+const BreadcrumbPage = forwardRef<React.ElementRef<typeof Text>, BreadcrumbPageProps>(
+  ({ className, ...props }, ref) => {
+    const { size } = useBreadcrumb();
+
+    return (
+      <Text
+        ref={ref}
+        aria-current="page"
+        accessibilityRole="text"
+        weight="medium"
+        className={crumbText({ size, className: cn('text-foreground', className) })}
+        {...props}
+      />
+    );
+  }
+);
+BreadcrumbPage.displayName = 'Breadcrumb.Page';
+
+export interface BreadcrumbSeparatorProps extends ViewProps {
+  className?: string;
+  /** Override the glyph for this one gap. Falls back to the root's separator. */
+  children?: ReactNode;
+}
+
+/**
+ * The glyph between crumbs. `Breadcrumb.List` inserts it for you; it is public
+ * only for the rare hand-assembled trail. Hidden from screen readers — the
+ * order of the crumbs already conveys the hierarchy.
+ */
+const BreadcrumbSeparator = forwardRef<View, BreadcrumbSeparatorProps>(
+  ({ className, children, ...props }, ref) => {
+    const { separator } = useBreadcrumb();
+    const rawTint = useCSSVariable('--color-muted-foreground');
+    const tint = typeof rawTint === 'string' ? rawTint : undefined;
+    const glyph = children ?? separator;
+
+    return (
+      <View
+        ref={ref}
+        aria-hidden
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+        className={cn('items-center justify-center', className)}
+        {...props}
+      >
+        {glyph ?? <ChevronRightIcon size={14} color={tint} />}
+      </View>
+    );
+  }
+);
+BreadcrumbSeparator.displayName = 'Breadcrumb.Separator';
+
+export interface BreadcrumbEllipsisProps
+  extends Omit<AnimatedPressableProps, 'children'> {
+  className?: string;
+}
+
+/**
+ * Stands in for the crumbs a collapsed trail hides. Static by default; give it
+ * an `onPress` (via the list's `onEllipsisPress`) and it becomes the trigger
+ * for a menu of the hidden steps. Labelled "Show more" so the collapse is not
+ * silent to assistive tech.
+ */
+const BreadcrumbEllipsis = forwardRef<View, BreadcrumbEllipsisProps>(
+  ({ className, onPress, ...props }, ref) => {
+    const rawTint = useCSSVariable('--color-muted-foreground');
+    const tint = typeof rawTint === 'string' ? rawTint : undefined;
+    const glyph = <EllipsisIcon size={16} color={tint} />;
+
+    if (!onPress) {
+      return (
+        <View
+          ref={ref}
+          accessibilityLabel="More"
+          className={cn('h-5 items-center justify-center px-0.5', className)}
+        >
+          {glyph}
+        </View>
+      );
+    }
+
+    return (
+      <AnimatedPressable
+        ref={ref}
+        accessibilityRole="button"
+        accessibilityLabel="Show more"
+        pressScale={0.92}
+        onPress={onPress}
+        className={cn('h-5 items-center justify-center px-0.5', className)}
+        {...props}
+      >
+        {glyph}
+      </AnimatedPressable>
+    );
+  }
+);
+BreadcrumbEllipsis.displayName = 'Breadcrumb.Ellipsis';
+
+export const Breadcrumb = Object.assign(BreadcrumbRoot, {
+  List: BreadcrumbList,
+  Item: BreadcrumbItem,
+  Link: BreadcrumbLink,
+  Page: BreadcrumbPage,
+  Separator: BreadcrumbSeparator,
+  Ellipsis: BreadcrumbEllipsis,
+});

package/src/components/chip/index.tsx

@@ -47,7 +47,7 @@ const chipVariants = tv({
     root: 'flex-row items-center self-start rounded-full border border-transparent',
     label: 'font-medium',
     close:
-      'items-center justify-center rounded-full -mr-1 aspect-square opacity-70',
+      'items-center justify-center rounded-full -me-1 aspect-square opacity-70',
   },
   variants: {
     variant: {
@@ -88,7 +88,7 @@ const chipVariants = tv({
     },
     /** Trims the trailing padding so the close target hugs the right edge. */
     closable: {
-      true: { root: 'pr-1' },
+      true: { root: 'pe-1' },
     },
     disabled: {
       true: { root: 'opacity-[0.56]' },

package/src/components/direction/index.tsx

@@ -33,16 +33,18 @@
  * comes from the device — so an app that did force RTL the old way still reads
  * back the truth.
  */
-import { createContext, useContext, useMemo, type ReactNode } from 'react';
-import { I18nManager, View, type ViewProps } from 'react-native';
-import { cn } from '../../utils/cn';
+import { useContext, useMemo, type ReactNode } from 'react';
+import { View, type ViewProps } from 'react-native';
+import {
+  DirectionContext,
+  deviceDirection,
+  useDirection,
+  useDirectionSign,
+  type DirectionValue,
+} from '../../hooks/use-direction';
 
-export type DirectionValue = 'ltr' | 'rtl';
-
-/** What the device is set to, for anything outside a provider. */
-const deviceDirection = (): DirectionValue => (I18nManager.isRTL ? 'rtl' : 'ltr');
-
-const DirectionContext = createContext<DirectionValue | null>(null);
+export { useDirection, useDirectionSign };
+export type { DirectionValue };
 
 export interface DirectionProps extends ViewProps {
   className?: string;
@@ -56,9 +58,14 @@ export interface DirectionProps extends ViewProps {
 }
 
 /**
- * Provider. Renders one `View` — it has to, since the flip is a style — which
- * fills its parent by default so it can wrap an app. Pass `className` to change
- * that: `flex-none` or a width class both win over the default.
+ * Provider. Renders one `View` — it has to, since the flip is a style.
+ *
+ * The view takes no layout of its own: it is as big as what is inside it, and
+ * `className` says otherwise. Wrapping a whole app therefore wants `flex-1`
+ * explicitly. It used to carry that by default, and every use inside a screen
+ * had to undo it with `flex-none` — a default that is wrong for one of its two
+ * uses is worse than no default, because the wrong one fails silently by
+ * swallowing the rest of the screen.
  */
 export function Direction({ className, children, dir, style, ...props }: DirectionProps) {
   const inherited = useContext(DirectionContext);
@@ -71,7 +78,7 @@ export function Direction({ className, children, dir, style, ...props }: Directi
 
   return (
     <DirectionContext.Provider value={value}>
-      <View className={cn('flex-1', className)} style={[directionStyle, style]} {...props}>
+      <View className={className} style={[directionStyle, style]} {...props}>
         {children}
       </View>
     </DirectionContext.Provider>
@@ -80,11 +87,3 @@ export function Direction({ className, children, dir, style, ...props }: Directi
 
 Direction.displayName = 'Direction';
 
-/**
- * The reading direction in force, for a component that has to flip maths Yoga
- * cannot flip for it. Safe with no provider mounted: it falls back to the
- * device's own setting.
- */
-export function useDirection(): DirectionValue {
-  return useContext(DirectionContext) ?? deviceDirection();
-}

package/src/components/frame/index.tsx

@@ -14,6 +14,23 @@
  * surfaces read as one misdrawn shape. The panel's bottom corners are not set
  * at all — the shell clips them, so they take its radius exactly.
  *
+ * That clip follows the shell's *border box*, not the box inside its border.
+ * Along the straight edges the panel is held off by the border width and the
+ * edge shows through, but at the corner arcs the panel's square corner is
+ * clipped to the outer radius and paints across the border. At the default
+ * hairline that is a sliver nobody sees. Give the shell a thicker border and
+ * the corners visibly eat it, so a Frame with `border-2` or more needs the
+ * panel told where to stop:
+ *
+ * ```tsx
+ * <Frame className="rounded-[28px] border-2 border-dashed">
+ *   <Frame.Panel className="rounded-b-[26px]">…</Frame.Panel>
+ * </Frame>
+ * ```
+ *
+ * The radius to use is the shell's less its border width. It is on the caller
+ * because both arrive as `className` strings, which the component cannot read.
+ *
  * ```tsx
  * <Frame>
  *   <Frame.Header>

package/src/components/heatmap-chart/index.tsx

@@ -65,14 +65,23 @@ const AnimatedRect = Animated.createAnimatedComponent(Rect);
 
 /**
  * Rows in a week — the default, and what the calendar helper and the weekday
- * labels assume. The grid itself takes a `rows` prop, so an hourly band or a
- * single-row uptime strip is the same component with a different number.
+ * labels assume. The grid itself takes a `rows` prop, so a grid whose bins are
+ * hours rather than days is the same component with a different number.
  */
 const DAYS_IN_WEEK = 7;
 
 /** Opacity of the base colour at each activity level. Index 0 is "nothing". */
 const LEVEL_OPACITY = [1, 0.28, 0.5, 0.74, 1] as const;
 
+/**
+ * A theme token rather than a colour. Tokens are named, not written, so the
+ * leading `--` tells the two apart without the caller having to say which
+ * kind they passed.
+ */
+function isToken(value: string | undefined): value is string {
+  return typeof value === 'string' && value.startsWith('--');
+}
+
 /** Room left for the weekday labels when the y-axis does not ask for its own. */
 const DEFAULT_AXIS_WIDTH = 26;
 
@@ -317,8 +326,8 @@ export interface HeatmapChartProps extends ViewProps {
   /** Which weekday is the top row. `0` is Sunday. Labels follow it. */
   weekStartDay?: number;
   /**
-   * Rows per column. Seven for a calendar; use another number for a band that
-   * is not a week — twenty-four for hours, one for an uptime strip.
+   * Rows per column. Seven for a calendar; use another number when the bins
+   * are not weekdays — twenty-four for a grid of hours.
    */
   rows?: number;
   /**
@@ -333,8 +342,27 @@ export interface HeatmapChartProps extends ViewProps {
    * opacities, which follows the theme.
    */
   levelColors?: string[];
-  /** Base colour for the derived ramp. Defaults to the `--color-chart-1` token. */
+  /**
+   * Base colour for the derived ramp — the colour the busiest cells are drawn
+   * in, with the quieter levels the same colour at lower opacity.
+   *
+   * Takes a theme token by name as well as a literal, so `"--color-chart-3"`
+   * recolours the chart and keeps following the theme through light and dark.
+   * Defaults to `--color-chart-1`.
+   */
   color?: string;
+  /**
+   * Colour of a cell with nothing in it. Takes a token name too. Defaults to
+   * `--color-muted`, which is the right weight for "measured, and empty" —
+   * override it for a chart that should read as denser or fainter than that.
+   */
+  emptyColor?: string;
+  /**
+   * Opacity of the base colour at each of the five levels, quietest first.
+   * The way to retune the ramp's contrast without having to name five colours.
+   * Ignored when `levelColors` is given, which sets the colours outright.
+   */
+  levelOpacity?: number[];
   /** Milliseconds for the reveal on mount. */
   animationDuration?: number;
   /** Opacity of every cell that is not the one under the finger. */
@@ -361,6 +389,8 @@ const HeatmapChartRoot = forwardRef<View, HeatmapChartProps>(function HeatmapCha
     levels,
     levelColors,
     color,
+    emptyColor,
+    levelOpacity,
     animationDuration = 900,
     inactiveOpacity = 1,
     onActiveCellChange,
@@ -378,10 +408,24 @@ const HeatmapChartRoot = forwardRef<View, HeatmapChartProps>(function HeatmapCha
   const reveal = useSharedValue(0);
   const reducedMotion = useReducedMotion();
 
-  const baseToken = useCSSVariable('--color-chart-1');
-  const emptyToken = useCSSVariable('--color-muted');
-  const base = color ?? (typeof baseToken === 'string' ? baseToken : '#262626');
-  const empty = typeof emptyToken === 'string' ? emptyToken : 'rgba(128,128,128,0.16)';
+  /*
+   * `color` and `emptyColor` take a token name as readily as a literal. A
+   * literal is a colour frozen at the moment it was written — it cannot follow
+   * the theme into dark mode — so naming the token is almost always what the
+   * caller meant, and having to resolve it themselves is the reason they did
+   * not. The hooks run unconditionally; which of the two answers is used is
+   * decided after.
+   */
+  const baseToken = useCSSVariable(isToken(color) ? color : '--color-chart-1');
+  const emptyToken = useCSSVariable(
+    isToken(emptyColor) ? emptyColor : '--color-muted'
+  );
+  const base =
+    (isToken(color) ? undefined : color) ??
+    (typeof baseToken === 'string' ? baseToken : '#262626');
+  const empty =
+    (isToken(emptyColor) ? undefined : emptyColor) ??
+    (typeof emptyToken === 'string' ? emptyToken : 'rgba(128,128,128,0.16)');
 
   const parts = useMemo(() => splitParts(children), [children]);
   // The y-axis is laid out beside the grid rather than over it, so its width
@@ -419,8 +463,11 @@ const HeatmapChartRoot = forwardRef<View, HeatmapChartProps>(function HeatmapCha
     () =>
       levelColors
         ? { ramp: levelColors, opacities: levelColors.map(() => 1) }
-        : { ramp: [empty, base, base, base, base], opacities: [...LEVEL_OPACITY] },
-    [levelColors, empty, base]
+        : {
+            ramp: [empty, base, base, base, base],
+            opacities: levelOpacity ?? [...LEVEL_OPACITY],
+          },
+    [levelColors, levelOpacity, empty, base]
   );
 
   const levelOf = useMemo(

package/src/components/input-group/index.tsx

@@ -26,8 +26,8 @@ import { Input, type InputProps } from '../input';
 const inputGroupVariants = tv({
   slots: {
     root: 'w-full',
-    prefix: 'absolute bottom-0 left-0 top-0 z-10 flex-row items-center justify-center gap-2 px-3',
-    suffix: 'absolute bottom-0 right-0 top-0 z-10 flex-row items-center justify-center gap-2 px-3',
+    prefix: 'absolute bottom-0 start-0 top-0 z-10 flex-row items-center justify-center gap-2 px-3',
+    suffix: 'absolute bottom-0 end-0 top-0 z-10 flex-row items-center justify-center gap-2 px-3',
   },
   variants: {
     isDisabled: {