panelui-native 0.13.0 → 0.16.0

package/lib/typescript/src/primitives/scroll-progress.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ScrollProgress — publishes a scroll container's position so children can
+ * animate against it.
+ *
+ * Scroll-driven effects all need the same two numbers: where the scroller is,
+ * and how tall its viewport is. Every component that wanted them measuring for
+ * itself would mean one scroll listener per effect and one measurement pass per
+ * effect per frame, for two values that are the same for all of them.
+ *
+ * It wraps the scroll view you already have rather than replacing it — the
+ * child is cloned with an animated scroll handler composed onto it, the same
+ * way `ScrollFade` does — so a `FlatList`, a `SectionList` or your own
+ * scrollable all work, and nothing has to be rewritten to adopt it.
+ *
+ * ```tsx
+ * <ScrollProgress>
+ *   <ScrollView>
+ *     <ScrollText>…</ScrollText>
+ *   </ScrollView>
+ * </ScrollProgress>
+ * ```
+ *
+ * Both values are shared values, so the whole chain from scroll event to
+ * animated style stays on the UI thread and nothing re-renders as you scroll.
+ */
+import { type ReactNode } from 'react';
+import { type ViewProps } from 'react-native';
+import { type SharedValue } from 'react-native-reanimated';
+export interface ScrollProgressValue {
+    /** Distance scrolled, in pixels. */
+    offset: SharedValue<number>;
+    /** Height of the visible area. */
+    viewport: SharedValue<number>;
+    /** Total height of the content. */
+    content: SharedValue<number>;
+    /**
+     * Window-space top edge of the scroller. What turns an element's measured
+     * `pageY` into a position inside *this* viewport rather than the screen's —
+     * they differ by whatever sits above the scroller, and assuming they do not
+     * is why scroll effects drift under a header.
+     */
+    top: SharedValue<number>;
+}
+/**
+ * The nearest enclosing scroll container's position, or `null` outside one.
+ *
+ * It returns null rather than throwing because every consumer of this also
+ * takes an explicit `progress` prop — a component that can be driven by hand
+ * should not insist on a provider it does not need.
+ */
+export declare function useScrollProgress(): ScrollProgressValue | null;
+export interface ScrollProgressProps extends ViewProps {
+    className?: string;
+    /** Exactly one scrollable — a ScrollView, FlatList, or anything like them. */
+    children?: ReactNode;
+}
+export declare function ScrollProgress({ className, children, ...props }: ScrollProgressProps): import("react").JSX.Element;
+export declare namespace ScrollProgress {
+    var displayName: string;
+}
+//# sourceMappingURL=scroll-progress.d.ts.map

package/lib/typescript/src/primitives/scroll-progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scroll-progress.d.ts","sourceRoot":"","sources":["../../../../src/primitives/scroll-progress.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EASL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AACf,OAAO,EAAgC,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAiB,EAKf,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,mBAAmB;IAClC,oCAAoC;IACpC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC9B,mCAAmC;IACnC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC7B;;;;;OAKG;IACH,GAAG,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC1B;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,GAAG,IAAI,CAE9D;AASD,MAAM,WAAW,mBAAoB,SAAQ,SAAS;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,wBAAgB,cAAc,CAAC,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,mBAAmB,+BA6EpF;yBA7Ee,cAAc"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panelui-native",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "High-performance React Native UI components for Expo. Semantic design tokens, powered by Uniwind (Tailwind v4) and Reanimated.",
   "main": "./lib/module/index.js",
   "module": "./lib/module/index.js",

package/src/components/button/index.tsx

@@ -115,22 +115,23 @@ export interface ButtonProps
    * `primary`/`destructive` → filled, `outline` → outlined, everything else
    * → text; `size` sets the height.
    *
-   * A native button **fills the width it is given**, because the host is told
-   * its size rather than left to measure the platform's content — which is
-   * what made it collapse and then jump on first press. Put it in a row to
-   * share the width, or in a narrower parent to shrink it.
+   * A native button **sizes itself to its label**, the way a platform button
+   * is supposed to. It does not stretch to fill its container, and `fullWidth`
+   * has no effect on it.
    */
   native?: boolean;
 }
 
 /**
- * Height given to the native host, matching the styled scale above.
+ * Height given to the platform button, matching the styled scale above.
  *
- * The host is told its size rather than asked to work it out. `matchContents`
- * measures the platform's own content a frame late and again when that content
- * changes — so the button renders at nothing, collapses against whatever sits
- * above it, and jolts into place on the first press. Width comes from ordinary
- * layout instead, which is why a native button fills its container.
+ * It goes on the button rather than on the host, and that distinction is the
+ * whole fix for the jump. A host sized to a number with an unsized control
+ * inside it hands the platform a box the control never agreed to: SwiftUI and
+ * Compose both lay out against their own intrinsic size and only settle into
+ * the box when something forces a second pass — which for a button is the
+ * first press. Given a definite height of its own, the button has nothing left
+ * to recompute, and the host follows it with `matchContents`.
  */
 const NATIVE_HEIGHT: Record<NonNullable<ButtonVariantProps['size']>, number> = {
   sm: 36,
@@ -199,11 +200,12 @@ export const Button = forwardRef<View, ButtonProps>(
       const isStringLabel = typeof children === 'string';
 
       return (
-        <Host style={{ height: NATIVE_HEIGHT[size ?? 'md'] }}>
+        <Host matchContents>
           <NativeButton
             label={isStringLabel ? children : undefined}
             variant={NATIVE_VARIANT[variant ?? 'primary']}
             disabled={isDisabled}
+            style={{ height: NATIVE_HEIGHT[size ?? 'md'] }}
             onPress={props.onPress}
           >
             {/* Non-string children are React Native views, and the native

package/src/components/direction/index.tsx

@@ -0,0 +1,90 @@
+/**
+ * Direction — reading direction for everything below it.
+ *
+ * ```tsx
+ * <Direction dir="rtl">
+ *   <App />
+ * </Direction>
+ * ```
+ *
+ * The layout flip is Yoga's, not ours: the wrapper carries the `direction`
+ * style, and every row, `start`/`end` inset and horizontal padding underneath
+ * it mirrors natively. That is the whole reason this is a component and not a
+ * bare context — `direction` is a *style*, so a subtree is the unit it applies
+ * to.
+ *
+ * It is also the reason to prefer it over flipping the process with
+ * `I18nManager.forceRTL`, which needs an app restart to take effect, cannot be
+ * scoped to part of a screen, and cannot be previewed side by side. Here the
+ * value is a prop: change it and the next frame is mirrored.
+ *
+ * ## What Yoga does not flip
+ *
+ * Anything measured in raw pixels rather than laid out — a drag translation, an
+ * indicator offset, the direction a sweep travels. Those have to consult the
+ * value and negate it themselves, which is what `useDirection()` is for:
+ *
+ * ```tsx
+ * const dir = useDirection();
+ * const delta = (dir === 'rtl' ? -event.translationX : event.translationX) / width;
+ * ```
+ *
+ * With no provider mounted, and for a `<Direction>` given no `dir`, the value
+ * 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';
+
+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 interface DirectionProps extends ViewProps {
+  className?: string;
+  children?: ReactNode;
+  /**
+   * Reading direction for this subtree. Defaults to the nearest enclosing
+   * `Direction`, or to the device when there is none — so a nested provider
+   * with no `dir` inherits rather than resetting to left-to-right.
+   */
+  dir?: DirectionValue;
+}
+
+/**
+ * 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.
+ */
+export function Direction({ className, children, dir, style, ...props }: DirectionProps) {
+  const inherited = useContext(DirectionContext);
+  const value = dir ?? inherited ?? deviceDirection();
+
+  // The style object is memoised because it is the thing that invalidates
+  // layout for the entire subtree — a fresh one each render would re-run Yoga
+  // on every parent render, for a value that almost never changes.
+  const directionStyle = useMemo(() => ({ direction: value }) as const, [value]);
+
+  return (
+    <DirectionContext.Provider value={value}>
+      <View className={cn('flex-1', className)} style={[directionStyle, style]} {...props}>
+        {children}
+      </View>
+    </DirectionContext.Provider>
+  );
+}
+
+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

@@ -1,23 +1,29 @@
 /**
- * Frame — a widget shell: a titled surface wrapping an inset panel of rows,
- * with an optional action on the header row and a caption underneath.
+ * Frame — a widget shell: a card of rows sitting in a tray, with the tray's
+ * one exposed strip along the top carrying the title.
  *
- * Layout follows the nested-radius rule (inner radius = outer radius minus the
- * gap between them), which is why the panel is `rounded-xl` inside a
- * `rounded-2xl` shell. Since v0.4.0 the radius scale is theme-scoped, so this
- * relationship holds while the absolute values change per theme.
+ * The two surfaces are nested rather than stacked, and only one edge of the
+ * outer one is ever visible. The panel is flush to the shell's left, right and
+ * bottom, so the shell reads as something the card is *sitting in* rather than
+ * as a border around it — and the strip left at the top is the header, which
+ * is why the header needs no rule under it and no background of its own.
+ *
+ * The shell's radius is the larger of the two, and the panel's top corners are
+ * tighter. That is the reverse of the usual nested-radius rule, and it is
+ * deliberate: with only the top corners free, matching them would make the two
+ * 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.
  *
  * ```tsx
  * <Frame>
  *   <Frame.Header>
- *     <Frame.Title>Usage Type</Frame.Title>
- *     <Frame.Action>Amount</Frame.Action>
+ *     <Frame.Title>Agent monitor</Frame.Title>
+ *     <Frame.Action>All agents under 25% token limit</Frame.Action>
  *   </Frame.Header>
  *   <Frame.Panel>
  *     <Frame.Row>…</Frame.Row>
  *     <Frame.Row>…</Frame.Row>
  *   </Frame.Panel>
- *   <Frame.Footer>Updated 2 minutes ago</Frame.Footer>
  * </Frame>
  * ```
  *
@@ -41,15 +47,24 @@ import { cn } from '../../utils/cn';
 const frameVariants = tv({
   slots: {
     root: '',
-    panel: 'overflow-hidden rounded-xl border border-border bg-card',
+    // Flush left, right and bottom: no side or bottom border, because the
+    // shell's own edge is already there, and no bottom radius, because the
+    // shell clips it. Only the top corners and the rule under the header are
+    // the panel's to draw.
+    panel: 'overflow-hidden rounded-t-2xl border-t border-border bg-card',
   },
   variants: {
     variant: {
-      default: { root: 'rounded-2xl border border-border bg-surface p-1.5' },
+      // `overflow-hidden` is load-bearing — it is what makes the panel's
+      // bottom corners take the shell's radius instead of squaring off
+      // against it.
+      default: {
+        root: 'overflow-hidden rounded-3xl border border-border bg-surface',
+      },
       // No shell: the panel is the whole widget. For a Frame nested inside a
       // card that already draws a border, where the shell's own edge sitting
       // just inside it reads as a double line.
-      plain: { root: '', panel: 'rounded-2xl' },
+      plain: { root: '', panel: 'rounded-3xl border border-border' },
     },
   },
   defaultVariants: {
@@ -83,15 +98,16 @@ export interface FrameHeaderProps extends FrameProps {
 }
 
 /**
- * The header row: title on the left, `Frame.Action` on the right. Add
- * `className="flex-col items-start"` when you want a description underneath.
+ * The header row — the strip of shell left exposed above the panel. Title on
+ * the left, `Frame.Action` on the right. Add `className="flex-col items-start"`
+ * when you want a description underneath.
  */
 const FrameHeader = forwardRef<View, FrameHeaderProps>(
   ({ className, ...props }, ref) => (
     <View
       ref={ref}
       className={cn(
-        'flex-row items-center justify-between gap-3 px-3 pb-2.5 pt-2',
+        'flex-row items-center justify-between gap-3 px-4 pb-3 pt-2.5',
         className
       )}
       {...props}
@@ -100,14 +116,12 @@ const FrameHeader = forwardRef<View, FrameHeaderProps>(
 );
 FrameHeader.displayName = 'Frame.Header';
 
+/**
+ * Muted by default. The header is a caption on the tray the card sits in, not
+ * a heading over a section — the card's own rows carry the weight.
+ */
 const FrameTitle = forwardRef<RNText, TextProps>(({ className, ...props }, ref) => (
-  <Text
-    ref={ref}
-    size="base"
-    weight="medium"
-    className={cn('text-foreground', className)}
-    {...props}
-  />
+  <Text ref={ref} size="sm" muted className={className} {...props} />
 ));
 FrameTitle.displayName = 'Frame.Title';
 
@@ -123,7 +137,7 @@ const FrameAction = forwardRef<View, FrameActionProps>(
   ({ className, children, ...props }, ref) => (
     <View ref={ref} className={cn('flex-row items-center gap-2', className)} {...props}>
       {typeof children === 'string' ? (
-        <Text size="base" muted>
+        <Text size="sm" muted>
           {children}
         </Text>
       ) : (
@@ -177,8 +191,8 @@ export interface FramePanelProps extends FrameProps {
 }
 
 /**
- * The inset card holding the frame's content — the raised surface sitting in
- * from the shell's edges, with its own smaller radius.
+ * The card holding the frame's content — flush to the shell on three sides,
+ * with the header strip above it.
  */
 const FramePanel = forwardRef<View, FramePanelProps>(
   ({ className, dividers = true, children, ...props }, ref) => (
@@ -284,30 +298,6 @@ FrameSection.displayName = 'Frame.Section';
 /** Parts the panel divides. Declared after them, since it holds references. */
 const DIVIDABLE = new Set<unknown>([FrameRow, FrameSection]);
 
-export interface FrameFooterProps extends FrameProps {
-  children?: ReactNode;
-}
-
-/** Muted caption under the panel. Strings are wrapped for you. */
-const FrameFooter = forwardRef<View, FrameFooterProps>(
-  ({ className, children, ...props }, ref) => (
-    <View
-      ref={ref}
-      className={cn('flex-row items-center gap-2 px-3 pb-1.5 pt-2.5', className)}
-      {...props}
-    >
-      {typeof children === 'string' ? (
-        <Text size="sm" muted>
-          {children}
-        </Text>
-      ) : (
-        children
-      )}
-    </View>
-  )
-);
-FrameFooter.displayName = 'Frame.Footer';
-
 export const Frame = Object.assign(FrameRoot, {
   Header: FrameHeader,
   Title: FrameTitle,
@@ -316,5 +306,4 @@ export const Frame = Object.assign(FrameRoot, {
   Panel: FramePanel,
   Section: FrameSection,
   Row: FrameRow,
-  Footer: FrameFooter,
 });