panelui-native 0.65.0 → 0.66.1

package/src/components/flow/flow-identifiers.ts

@@ -0,0 +1,98 @@
+const FLOW_TOKEN_PREFIX = 'panelui-flow:';
+
+export interface FlowEndpoint {
+  node: string;
+  handle?: string;
+}
+
+export type FlowEndpointReference = string | FlowEndpoint;
+
+type EncodedReference = ['legacy', string] | ['endpoint', string] | ['endpoint', string, string];
+
+function encodedReference(reference: FlowEndpointReference): EncodedReference {
+  if (typeof reference === 'string') return ['legacy', reference];
+  return reference.handle === undefined
+    ? ['endpoint', reference.node]
+    : ['endpoint', reference.node, reference.handle];
+}
+
+function decodedReference(value: unknown): FlowEndpointReference | undefined {
+  if (!Array.isArray(value)) return undefined;
+  if (value.length === 2 && value[0] === 'legacy' && typeof value[1] === 'string') {
+    return value[1];
+  }
+  if (
+    (value.length === 2 || value.length === 3) &&
+    value[0] === 'endpoint' &&
+    typeof value[1] === 'string' &&
+    (value.length === 2 || typeof value[2] === 'string')
+  ) {
+    return value.length === 2 ? { node: value[1] } : { node: value[1], handle: value[2] };
+  }
+  return undefined;
+}
+
+function decodeToken(token: string): unknown[] | undefined {
+  if (!token.startsWith(FLOW_TOKEN_PREFIX)) return undefined;
+  try {
+    const value: unknown = JSON.parse(token.slice(FLOW_TOKEN_PREFIX.length));
+    return Array.isArray(value) ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Opaque identity for a registered handle. Node and handle text remain untouched. */
+export function encodeFlowHandleKey(node: string, handle: string): string {
+  return FLOW_TOKEN_PREFIX + JSON.stringify(['handle', node, handle]);
+}
+
+export function decodeFlowHandleKey(token: string): FlowEndpoint | undefined {
+  const value = decodeToken(token);
+  if (
+    value?.length !== 3 ||
+    value[0] !== 'handle' ||
+    typeof value[1] !== 'string' ||
+    typeof value[2] !== 'string'
+  ) {
+    return undefined;
+  }
+  return { node: value[1], handle: value[2] };
+}
+
+/** Opaque identity for an edge registration or accessibility connection action. */
+export function encodeFlowEdgeKey(
+  from: FlowEndpointReference,
+  to: FlowEndpointReference
+): string {
+  return FLOW_TOKEN_PREFIX + JSON.stringify(['edge', encodedReference(from), encodedReference(to)]);
+}
+
+export function decodeFlowEdgeKey(
+  token: string
+): { from: FlowEndpointReference; to: FlowEndpointReference } | undefined {
+  const value = decodeToken(token);
+  if (value?.length !== 3 || value[0] !== 'edge') return undefined;
+  const from = decodedReference(value[1]);
+  const to = decodedReference(value[2]);
+  return from === undefined || to === undefined ? undefined : { from, to };
+}
+
+/**
+ * Resolve a public endpoint without splitting its identifiers. Exact node ids
+ * win; legacy `node.handle` text is accepted only when it names one registered
+ * handle. Structured endpoints cover the otherwise ambiguous case.
+ */
+export function resolveFlowEndpoint(
+  reference: FlowEndpointReference,
+  nodes: readonly string[],
+  handles: readonly { node: string; id: string }[]
+): FlowEndpoint {
+  if (typeof reference !== 'string') return reference;
+  if (nodes.includes(reference)) return { node: reference };
+
+  const matches = handles.filter((handle) => `${handle.node}.${handle.id}` === reference);
+  return matches.length === 1
+    ? { node: matches[0]!.node, handle: matches[0]!.id }
+    : { node: reference };
+}

package/src/components/flow/index.tsx

@@ -107,6 +107,13 @@ import {
   type FlowAccessibilityHandle,
   type FlowAccessibilityNode,
 } from './flow-accessibility';
+import {
+  encodeFlowEdgeKey,
+  encodeFlowHandleKey,
+  resolveFlowEndpoint,
+  type FlowEndpoint,
+  type FlowEndpointReference,
+} from './flow-identifiers';
 
 const AnimatedPath = Animated.createAnimatedComponent(Path);
 const AnimatedRect = Animated.createAnimatedComponent(Rect);
@@ -1314,7 +1321,7 @@ function FlowHandle({
     unregisterHandle,
     connectNodes,
   } = flow;
-  const key = `${node}.${id}`;
+  const key = encodeFlowHandleKey(node, id);
 
   useEffect(() => {
     registerHandle({
@@ -1481,10 +1488,10 @@ FlowHandle.displayName = 'Flow.Handle';
 /* -------------------------------------------------------------------------- */
 
 export interface FlowEdgeProps {
-  /** Source, as `"nodeId"` or `"nodeId.handleId"`. */
-  from: string;
-  /** Target, same shape. */
-  to: string;
+  /** Source node or handle. Strings retain the `"nodeId.handleId"` shorthand. */
+  from: FlowEndpointReference;
+  /** Target node or handle, in the same shape. */
+  to: FlowEndpointReference;
   /** How the edge is routed. */
   variant?: FlowEdgeVariant;
   /**
@@ -1530,7 +1537,7 @@ export interface FlowEdgeProps {
  */
 function FlowEdge(props: FlowEdgeProps) {
   const { registerEdge, unregisterEdge } = useFlow('Flow.Edge');
-  const key = `${props.from}->${props.to}`;
+  const key = encodeFlowEdgeKey(props.from, props.to);
 
   // Re-registered whenever any prop changes, so `animated` toggling or a
   // variant switch reaches the layer that draws it.
@@ -1571,8 +1578,9 @@ function FlowEdgePath({
   tint: string;
   origin: { x: number; y: number };
 }) {
-  const source = resolveEnd(from, fromSide, handles);
-  const target = resolveEnd(to, toSide, handles);
+  const nodes = Object.keys(boxes);
+  const source = resolveEnd(from, fromSide, nodes, handles);
+  const target = resolveEnd(to, toSide, nodes, handles);
 
   const fromRect = boxes[source.node];
   const toRect = boxes[target.node];
@@ -1631,22 +1639,24 @@ function FlowEdgePath({
 }
 
 /**
- * Splits `"node"` or `"node.handle"` into the node and, when a handle was
- * named, the face and offset that handle registered.
+ * Resolves a node or handle without parsing either identifier. Legacy
+ * `"node.handle"` references are matched against the structured registry.
  */
 function resolveEnd(
-  reference: string,
+  reference: FlowEndpointReference,
   explicit: FlowSide | undefined,
+  nodes: string[],
   handles: HandleEntry[]
 ): { node: string; side: FlowSide | undefined; offset: number } {
-  const dot = reference.indexOf('.');
-  if (dot === -1) {
-    return { node: reference, side: explicit, offset: 0.5 };
-  }
-  const node = reference.slice(0, dot);
-  const entry = handles.find((handle) => handle.key === reference);
+  const endpoint = resolveFlowEndpoint(reference, nodes, handles);
+  const entry =
+    endpoint.handle === undefined
+      ? undefined
+      : handles.find(
+          (handle) => handle.node === endpoint.node && handle.id === endpoint.handle
+        );
   return {
-    node,
+    node: endpoint.node,
     side: explicit ?? entry?.side,
     offset: entry?.offset ?? 0.5,
   };
@@ -2199,4 +2209,4 @@ export const Flow = Object.assign(FlowRoot, {
   MiniMap: FlowMiniMap,
 });
 
-export type { FlowSide, FlowRect, FlowPoint };
+export type { FlowEndpoint, FlowEndpointReference, FlowSide, FlowRect, FlowPoint };

package/src/components/message-scroller/index.tsx

@@ -57,9 +57,12 @@ import { ChevronDownIcon } from '../../icons';
 import { AnimatedPressable } from '../../primitives/animated-pressable';
 import { cn } from '../../utils/cn';
 import { textChildren } from '../../primitives/text';
+import {
+  distanceFromMessageScrollerTarget,
+  isMessageScrollerTargetVisible,
+  MESSAGE_SCROLLER_EDGE_THRESHOLD,
+} from './message-scroller-math';
 
-/** Within this many pixels of the bottom still counts as being at the bottom. */
-const END_THRESHOLD = 24;
 /**
  * How much of the previous turn is left showing above an anchored one. Scrolling
  * a turn flush to the top reads as content having been cut off; a sliver of the
@@ -71,8 +74,11 @@ export type MessageScrollerPosition = 'start' | 'end' | 'last-anchor';
 
 interface MessageScrollerContextValue {
   scrollRef: ReturnType<typeof useAnimatedRef<Animated.ScrollView>>;
-  /** 1 while the reader is at the live edge, 0 otherwise. Drives the button. */
+  /** 1 while the reader is at the live edge, 0 otherwise. Drives follow state. */
   atEnd: ReturnType<typeof useSharedValue<number>>;
+  /** Live distance from each edge, used by target-specific jump controls. */
+  distanceFromStart: ReturnType<typeof useSharedValue<number>>;
+  distanceFromEnd: ReturnType<typeof useSharedValue<number>>;
   atEndJS: boolean;
   setAtEndJS: (atEnd: boolean) => void;
   autoScroll: boolean;
@@ -150,6 +156,11 @@ function MessageScrollerRoot({
 }: MessageScrollerProps) {
   const scrollRef = useAnimatedRef<Animated.ScrollView>();
   const atEnd = useSharedValue(1);
+  const awayFromEdge = MESSAGE_SCROLLER_EDGE_THRESHOLD + 1;
+  const distanceFromStart = useSharedValue(
+    defaultScrollPosition === 'start' ? 0 : awayFromEdge
+  );
+  const distanceFromEnd = useSharedValue(defaultScrollPosition === 'end' ? 0 : awayFromEdge);
   const [atEndJS, setAtEndJS] = useState(true);
   const [currentAnchorId, setCurrentAnchorId] = useState<string | null>(null);
 
@@ -199,6 +210,8 @@ function MessageScrollerRoot({
     () => ({
       scrollRef,
       atEnd,
+      distanceFromStart,
+      distanceFromEnd,
       atEndJS,
       setAtEndJS,
       autoScroll,
@@ -218,6 +231,8 @@ function MessageScrollerRoot({
     [
       scrollRef,
       atEnd,
+      distanceFromStart,
+      distanceFromEnd,
       atEndJS,
       autoScroll,
       preserveScrollOnPrepend,
@@ -268,6 +283,8 @@ function MessageScrollerViewport({
   const {
     scrollRef,
     atEnd,
+    distanceFromStart,
+    distanceFromEnd,
     setAtEndJS,
     autoScroll,
     preserveScrollOnPrepend,
@@ -310,8 +327,19 @@ function MessageScrollerViewport({
       const { contentOffset, contentSize, layoutMeasurement } = event;
       offsetY.value = contentOffset.y;
 
-      const distance = contentSize.height - layoutMeasurement.height - contentOffset.y;
-      const next = distance <= END_THRESHOLD ? 1 : 0;
+      distanceFromStart.value = distanceFromMessageScrollerTarget(
+        'start',
+        contentOffset.y,
+        contentSize.height,
+        layoutMeasurement.height
+      );
+      distanceFromEnd.value = distanceFromMessageScrollerTarget(
+        'end',
+        contentOffset.y,
+        contentSize.height,
+        layoutMeasurement.height
+      );
+      const next = isMessageScrollerTargetVisible(distanceFromEnd.value) ? 0 : 1;
       if (next !== atEnd.value) {
         atEnd.value = next;
         runOnJS(publishAtEnd)(next === 1);
@@ -515,12 +543,16 @@ function MessageScrollerButton({
   children,
   ...props
 }: MessageScrollerButtonProps) {
-  const { atEnd, scrollToEnd, scrollToStart } = useScroller('MessageScroller.Button');
+  const { distanceFromStart, distanceFromEnd, scrollToEnd, scrollToStart } =
+    useScroller('MessageScroller.Button');
   const tint = useCSSVariable('--color-foreground');
 
+  const targetDistance = target === 'end' ? distanceFromEnd : distanceFromStart;
   // Shown when away from the edge the button points at.
   const shown = useDerivedValue(() =>
-    withTiming(target === 'end' ? 1 - atEnd.value : atEnd.value, { duration: 160 })
+    withTiming(isMessageScrollerTargetVisible(targetDistance.value) ? 1 : 0, {
+      duration: 160,
+    })
   );
 
   const style = useAnimatedStyle(() => ({

package/src/components/message-scroller/message-scroller-math.ts

@@ -0,0 +1,24 @@
+type MessageScrollerTarget = 'start' | 'end';
+
+export const MESSAGE_SCROLLER_EDGE_THRESHOLD = 24;
+
+/** Distance from the viewport to the edge a jump button targets. */
+export function distanceFromMessageScrollerTarget(
+  target: MessageScrollerTarget,
+  contentOffsetY: number,
+  contentHeight: number,
+  viewportHeight: number
+): number {
+  'worklet';
+
+  const maximumOffset = Math.max(0, contentHeight - viewportHeight);
+  const boundedOffset = Math.min(maximumOffset, Math.max(0, contentOffsetY));
+  return target === 'start' ? boundedOffset : maximumOffset - boundedOffset;
+}
+
+/** Whether the control has enough distance to its target edge to be useful. */
+export function isMessageScrollerTargetVisible(distance: number): boolean {
+  'worklet';
+
+  return distance > MESSAGE_SCROLLER_EDGE_THRESHOLD;
+}

package/src/components/popover/index.tsx

@@ -321,6 +321,9 @@ export interface PopoverContentProps extends ViewProps {
    * Frost the background behind the panel instead of dimming it. Uses
    * `expo-blur` when installed and falls back to the dimmed scrim when it is
    * not, so it is safe to pass either way.
+   *
+   * Someone who has Reduce Transparency switched on gets an opaque
+   * backdrop instead, which is the whole point of the setting.
    */
   blur?: boolean;
   /**

package/src/components/selection-mode/index.tsx

@@ -88,6 +88,15 @@ import { Text, textChildren } from '../../primitives/text';
 import { cn } from '../../utils/cn';
 import { selectionTick } from '../../utils/haptics';
 import { BottomSheet } from '../bottom-sheet';
+import {
+  canEnterSelection,
+  handleSelectionItemPress,
+  selectAllValues,
+  selectionOwnsPress,
+  selectionTarget,
+  selectValue,
+  toggleValue,
+} from './selection-mode-contracts';
 
 /** How long the circle takes to come and go, in milliseconds. */
 const REVEAL_DURATION = 180;
@@ -293,11 +302,12 @@ function SelectionModeRoot({
       // Entering with the row that was pressed already picked. Entering with
       // nothing picked leaves the reader in a list that has changed under them
       // with nothing to show for it.
-      if (value !== undefined && !selectedRef.current.includes(value)) {
-        setSelected([...selectedRef.current, value]);
+      if (value !== undefined) {
+        const next = selectValue(selectedRef.current, value, max);
+        if (next !== selectedRef.current) setSelected(next);
       }
     },
-    [haptics, setActive, setSelected]
+    [haptics, max, setActive, setSelected]
   );
 
   /*
@@ -321,13 +331,10 @@ function SelectionModeRoot({
   const toggle = useCallback(
     (value: string) => {
       const current = selectedRef.current;
-      if (current.includes(value)) {
-        setSelected(current.filter((entry) => entry !== value));
-      } else {
-        if (max !== undefined && current.length >= max) return;
-        if (haptics) selectionTick();
-        setSelected([...current, value]);
-      }
+      const next = toggleValue(current, value, max);
+      if (next === current) return;
+      if (!current.includes(value) && haptics) selectionTick();
+      setSelected(next);
     },
     [max, haptics, setSelected]
   );
@@ -336,15 +343,15 @@ function SelectionModeRoot({
     if (!values) return;
     // At the limit rather than refusing: somebody who asked for all of them and
     // can only have twenty wants the twenty, not an error.
-    setSelected(max === undefined ? [...values] : values.slice(0, max));
+    setSelected(selectAllValues(values, max));
   }, [values, max, setSelected]);
 
   const clear = useCallback(() => setSelected([]), [setSelected]);
 
   const total = values?.length ?? 0;
   const count = selected.length;
-  const allSelected =
-    total > 0 && count >= (max === undefined ? total : Math.min(total, max));
+  const target = selectionTarget(total, max);
+  const allSelected = target > 0 && count >= target;
 
   // An open mode owns the back button: back should leave the mode, not the
   // screen the list is on.
@@ -459,10 +466,11 @@ export interface SelectionModeItemProps extends Omit<ViewProps, 'children'> {
   className?: string;
   /** This row's id. What ends up in `selected`. */
   value: string;
-  /** What the row does when it is pressed and the mode is off. */
+  /** What the row does whenever selection does not own its press. */
   onPress?: () => void;
   /**
-   * Stop this row entering selection mode, and being picked once in it. For a
+   * Stop this row entering selection mode, and being picked once in it. Its
+   * ordinary `onPress` still runs, including while selection is active. For a
    * header row, an advert, a "load more" — anything in the list that is not one
    * of the things being chosen between.
    */
@@ -487,8 +495,9 @@ export interface SelectionModeItemProps extends Omit<ViewProps, 'children'> {
  *
  * The press behaviour is the whole component: off mode, a press is the row's
  * own and a long press turns the mode on with this row picked; in it, a press
- * picks and unpicks and the row's own press is unreachable. Two meanings for
- * one gesture is exactly why the mode has to be visible from the header.
+ * picks and unpicks. A row excluded from selection keeps its ordinary press in
+ * both states. Two meanings for one gesture is exactly why the mode has to be
+ * visible from the header.
  */
 function SelectionModeItem({
   className,
@@ -503,6 +512,7 @@ function SelectionModeItem({
   const { active, enter, toggle, isSelected, sheet } = useSelectionMode();
   const selected = isSelected(value);
   const showing = alwaysShowIndicator || active;
+  const selecting = selectionOwnsPress(active, disabled);
   const reducedMotion = useReducedMotion();
 
   const context = useMemo(() => ({ value }), [value]);
@@ -537,23 +547,20 @@ function SelectionModeItem({
   return (
     <SelectionModeItemContext.Provider value={context}>
       <Pressable
-        accessibilityRole={showing ? 'checkbox' : 'button'}
-        accessibilityState={showing ? { checked: selected, disabled } : { disabled }}
-        // The row is unreachable in selection mode, so a screen reader is told
-        // what pressing it does now rather than what it used to do.
+        accessibilityRole={selecting ? 'checkbox' : 'button'}
+        accessibilityState={selecting ? { checked: selected } : undefined}
+        // Eligible rows become checkboxes only while selection owns their
+        // press. Excluded rows remain ordinary buttons because their action is
+        // still available.
         accessibilityHint={
-          showing ? undefined : disabled ? undefined : 'Long press to select'
+          active || disabled ? undefined : 'Long press to select'
         }
-        disabled={disabled && showing}
         onPress={() => {
-          if (disabled) return;
-          if (showing) toggle(value);
-          else onPress?.();
-        }}
-        onLongPress={sheet ? undefined : () => {
-          if (disabled || showing) return;
-          enter(value);
+          handleSelectionItemPress(active, disabled, () => toggle(value), onPress);
         }}
+        onLongPress={
+          canEnterSelection(active, disabled, sheet) ? () => enter(value) : undefined
+        }
         className={cn(
           indicator === 'leading' ? 'flex-row items-center gap-3 px-4 py-2.5' : '',
           className

package/src/components/selection-mode/selection-mode-contracts.ts

@@ -0,0 +1,53 @@
+/** The effective selection cap. Invalid and negative caps allow no additions. */
+function selectionLimit(max?: number): number {
+  if (max === undefined || max === Infinity) return Infinity;
+  return Number.isFinite(max) ? Math.max(0, Math.floor(max)) : 0;
+}
+
+/** Add one value without duplicating it or crossing the configured cap. */
+export function selectValue(selected: string[], value: string, max?: number): string[] {
+  if (selected.includes(value) || !(selected.length < selectionLimit(max))) return selected;
+  return [...selected, value];
+}
+
+/** Remove an existing value, or add it under the same contract used by entry. */
+export function toggleValue(selected: string[], value: string, max?: number): string[] {
+  return selected.includes(value)
+    ? selected.filter((entry) => entry !== value)
+    : selectValue(selected, value, max);
+}
+
+/** The values produced by select-all, capped by the same normalized limit. */
+export function selectAllValues(values: string[], max?: number): string[] {
+  const limit = selectionLimit(max);
+  return limit === Infinity ? [...values] : values.slice(0, limit);
+}
+
+/** How many selections constitute all selectable values. */
+export function selectionTarget(total: number, max?: number): number {
+  return Math.min(total, selectionLimit(max));
+}
+
+/**
+ * A selection-ineligible row keeps its ordinary action in every mode. Only an
+ * active, eligible row gives its press to selection.
+ */
+export function selectionOwnsPress(active: boolean, disabled: boolean): boolean {
+  return active && !disabled;
+}
+
+/** Execute the one action owned by a row press under the interaction contract. */
+export function handleSelectionItemPress(
+  active: boolean,
+  disabled: boolean,
+  toggle: () => void,
+  action?: () => void
+): void {
+  if (selectionOwnsPress(active, disabled)) toggle();
+  else action?.();
+}
+
+/** Long press enters only from an inactive screen row that can be selected. */
+export function canEnterSelection(active: boolean, disabled: boolean, sheet: boolean): boolean {
+  return !active && !disabled && !sheet;
+}