pixelize-native-library 1.2.0 → 1.3.0

package/lib/module/modules/list-item/ListItem.js

@@ -1,16 +1,18 @@
 "use strict";
 
 /**
- * ListItem — a row primitive. It is rendered AS a list cell at scale, so it carries no mount
- * animation and no loop: the only motion is `usePressMotion`, which starts on touch and runs on the
- * native driver. The pressable root is an animated `Pressable` rather than an `Animated.View`
- * wrapper so a 5000-row list pays for no extra node.
+ * ListItem — a row primitive. Press feedback uses `usePressState` (scale + state-layer overlay).
  */
 
 import { memo, useMemo } from "react";
-import { Animated, Pressable, Text, View } from "react-native";
-import { usePressMotion } from "../../core/motion/index.js";
+import { Platform, Pressable, StyleSheet, View } from "react-native";
+import Animated, { FadeInDown, FadeOut, LinearTransition, ReduceMotion } from "react-native-reanimated";
+import { usePressState } from "../../core/motion/usePressState.js";
+import { renderNodeSlot } from "../../core/slot/index.js";
+import { concentric } from "../../core/style/index.js";
+import { rippleColor as androidRippleColor, stateLayerScrim } from "../../theme/platform/stateLayer.native.js";
 import { useTheme } from "../../theme/hooks.js";
+import { Text } from "../text/index.js";
 import { listItemBodyStructure, listItemDotStructure, listItemStructure, resolveListItemAccessibility, resolveListItemColors } from "./ListItem.variants.js";
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const AnimatedPressable = Animated.createAnimatedComponent(Pressable);
@@ -21,12 +23,15 @@ export const ListItem = /*#__PURE__*/memo(function ListItem({
   trailing,
   unread = false,
   onPress,
+  accessibilityLabel,
+  accessibilityState,
   style,
   testID
 }) {
   const theme = useTheme();
   const pressable = onPress !== undefined;
-  const press = usePressMotion(!pressable);
+  const press = usePressState(!pressable);
+  const leadingRadius = useMemo(() => concentric(theme.radii.lg, theme.space[4]), [theme.radii.lg, theme.space]);
   const colors = useMemo(() => resolveListItemColors(theme.colors, unread), [theme.colors, unread]);
   const a11y = useMemo(() => resolveListItemAccessibility({
     title,
@@ -36,57 +41,85 @@ export const ListItem = /*#__PURE__*/memo(function ListItem({
   const baseStyle = useMemo(() => [listItemStructure(theme), {
     backgroundColor: colors.background
   }, style], [theme, colors, style]);
-  // `style` stays last; the press style holds only opacity/transform, which `LayoutStyle` cannot name.
   const pressableStyle = useMemo(() => [listItemStructure(theme), {
-    backgroundColor: colors.background
-  }, press.style, style], [theme, colors, press.style, style]);
+    backgroundColor: colors.background,
+    overflow: "hidden"
+  }, press.animatedStyle, style], [theme, colors, press.animatedStyle, style]);
+  const overlayStaticStyle = useMemo(() => ({
+    backgroundColor: stateLayerScrim(theme.mode),
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous"
+  }), [theme.mode, theme.radii.md]);
+  const androidRipple = useMemo(() => {
+    if (!pressable || Platform.OS !== "android") return undefined;
+    return {
+      color: androidRippleColor(theme.mode),
+      borderless: false
+    };
+  }, [pressable, theme.mode]);
   const dotStyle = useMemo(() => [listItemDotStructure(theme), {
     backgroundColor: colors.dot
   }], [theme, colors]);
   const bodyStyle = useMemo(() => listItemBodyStructure(theme), [theme]);
-  const titleStyle = useMemo(() => [theme.fontStyleForWeight(unread ? theme.fontWeights.semibold : theme.fontWeights.medium), {
-    fontSize: theme.fontSizes.md,
-    color: colors.title
-  }], [theme, unread, colors]);
-  const subtitleStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
+  const slotTextStyle = useMemo(() => [theme.fontStyleForWeight(theme.fontWeights.regular), {
     fontSize: theme.fontSizes.sm,
-    color: colors.subtitle
-  }], [theme, colors]);
+    color: theme.colors.fg.muted
+  }], [theme]);
   const body = /*#__PURE__*/_jsxs(_Fragment, {
     children: [unread && /*#__PURE__*/_jsx(View, {
       testID: testID === undefined ? undefined : `${testID}-dot`,
       accessibilityElementsHidden: true,
       importantForAccessibility: "no-hide-descendants",
       style: dotStyle
-    }), leading, /*#__PURE__*/_jsxs(View, {
+    }), leading !== undefined && /*#__PURE__*/_jsx(View, {
+      style: {
+        borderRadius: leadingRadius,
+        borderCurve: "continuous",
+        overflow: "hidden"
+      },
+      children: renderNodeSlot(leading, slotTextStyle)
+    }), /*#__PURE__*/_jsxs(View, {
       style: bodyStyle,
       children: [/*#__PURE__*/_jsx(Text, {
+        variant: "body",
+        weight: unread ? "semibold" : "medium",
         numberOfLines: 1,
-        style: titleStyle,
         children: title
       }), subtitle !== undefined && /*#__PURE__*/_jsx(Text, {
+        variant: "caption",
+        color: "muted",
         numberOfLines: 2,
-        style: subtitleStyle,
         children: subtitle
       })]
-    }), trailing]
+    }), renderNodeSlot(trailing, slotTextStyle)]
   });
   if (!pressable) {
-    return /*#__PURE__*/_jsx(View, {
+    return /*#__PURE__*/_jsx(Animated.View, {
+      entering: FadeInDown.springify().reduceMotion(ReduceMotion.System),
+      exiting: FadeOut.reduceMotion(ReduceMotion.System),
+      layout: LinearTransition.reduceMotion(ReduceMotion.System),
       testID: testID,
       style: baseStyle,
       children: body
     });
   }
-  return /*#__PURE__*/_jsx(AnimatedPressable, {
+  return /*#__PURE__*/_jsxs(AnimatedPressable, {
     testID: testID,
     accessibilityRole: "button",
-    accessibilityLabel: a11y.accessibilityLabel,
+    accessibilityLabel: accessibilityLabel ?? a11y.accessibilityLabel,
+    accessibilityState: accessibilityState,
     onPress: onPress,
-    onPressIn: press.onPressIn,
-    onPressOut: press.onPressOut,
+    onPressIn: press.handlers.onPressIn,
+    onPressOut: press.handlers.onPressOut,
+    onLayout: press.onLayout,
+    android_ripple: androidRipple,
     style: pressableStyle,
-    children: body
+    children: [/*#__PURE__*/_jsx(Animated.View, {
+      testID: testID === undefined ? undefined : `${testID}-press-overlay`,
+      style: [StyleSheet.absoluteFill, overlayStaticStyle, press.overlayStyle, {
+        pointerEvents: 'none'
+      }]
+    }), body]
   });
 });
 //# sourceMappingURL=ListItem.js.map

package/lib/module/modules/list-item/ListItem.variants.js

@@ -1,13 +1,15 @@
 "use strict";
 
+import { StyleSheet } from "react-native";
 /**
  * Pure resolvers for ListItem — no React, so the WCAG tests import this directly (mocking only
  * `react-native`'s `StyleSheet`, as every sibling module's tests do).
  */
 
 import { createThemedVariants } from "../../core/style/index.js";
+import { floatingBackground, floatingSurfaceStyle } from "../../theme/platform/floatingSurface.native.js";
 export const LIST_ITEM_DOT_SIZE = 8;
-export const LIST_ITEM_MIN_HEIGHT = 44;
+export const LIST_ITEM_MIN_HEIGHT = 56;
 export function resolveListItemColors(colors, unread) {
   return {
     background: unread ? colors.bg.surface : undefined,
@@ -34,7 +36,8 @@ export const listItemStructure = createThemedVariants(theme => ({
     columnGap: theme.space[3],
     minHeight: LIST_ITEM_MIN_HEIGHT,
     paddingVertical: theme.space[3],
-    paddingHorizontal: theme.space[4]
+    paddingHorizontal: theme.space[4],
+    borderBottomWidth: StyleSheet.hairlineWidth
   }
 }));
 export const listItemBodyStructure = createThemedVariants(theme => ({
@@ -43,6 +46,12 @@ export const listItemBodyStructure = createThemedVariants(theme => ({
     rowGap: theme.space[1]
   }
 }));
+export function listItemRaisedStyle(theme) {
+  return {
+    backgroundColor: floatingBackground(theme, "sm"),
+    ...floatingSurfaceStyle(theme, "sm")
+  };
+}
 export const listItemDotStructure = createThemedVariants(theme => ({
   base: {
     width: LIST_ITEM_DOT_SIZE,

package/lib/module/modules/list-item/ListItemProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=ListItemProps.js.map

package/lib/module/modules/list-item/MODULE.md

@@ -3,9 +3,8 @@
 `ListItem` renders one row for notification lists, inboxes, and settings screens: optional
 `leading`/`trailing` nodes around a title + subtitle column. `unread` adds an `accent.solid` dot
 and a `bg.surface` row emphasis (plus a semibold title) — `bg.surface`, not `bg.selected`, because
-`fg.muted` is only measured AA against surface/hover. A `Pressable` when `onPress` is set
-(`bg.sunken` pressed fill — measured, `fg.default` fails AA on `bg.hover` on 4 light brands),
-a plain `View` otherwise.
+`fg.muted` is only measured AA against surface/hover. With `onPress` the root is a
+`Pressable`; without it, an `Animated.View` (see Motion).
 
 ## Files
 
@@ -16,6 +15,7 @@ a plain `View` otherwise.
 | `index.ts` | Public surface: `ListItem`, `ListItemProps`. |
 | `__tests__/ListItem.test.ts` | Pure: WCAG contrast (all brands × modes) + a11y label contract. |
 | `__tests__/ListItem.render.test.tsx` | Render: unread dot/bg, press, leading/trailing slots. |
+| `__tests__/ListItem.dom.test.tsx` | Real DOM (`jest.web.config.js`). |
 
 ## Props
 
@@ -27,6 +27,8 @@ a plain `View` otherwise.
 | `trailing` | `ReactNode` | — | E.g. a timestamp `Text` or `Badge`. |
 | `unread` | `boolean` | `false` | Accent dot (decorative, hidden from AT — "unread" is announced in the label instead) + `bg.surface` fill. |
 | `onPress` | `() => void` | — | Row becomes a `button`-role Pressable, min 44dp tall. |
+| `accessibilityLabel` | `string` | — | Overrides the default `"title, subtitle, unread?"` label on pressable rows. |
+| `accessibilityState` | `{ disabled?, selected? }` | — | Merged into the pressable row (e.g. `selected` for inbox selection). |
 | `style` | `LayoutStyle` | — | Layout-only, outermost, applied exactly once, last. |
 | `testID` | `string` | — | Also derives the `-dot` sub-id. |
 
@@ -35,19 +37,21 @@ a plain `View` otherwise.
 - Pressable rows carry `accessibilityLabel = "title, subtitle, unread?"` so the dot never has to
   speak for itself; non-pressable rows leave the text nodes in the normal tree.
 - Title/subtitle are measured ≥ 4.5:1 against the canvas, the `bg.surface` unread fill, and the
-  `bg.sunken` pressed fill for all 8 brands × both modes (`ListItem.test.ts`).
+  `bg.sunken` pressed fill for all 9 brands × both modes (`ListItem.test.ts`).
 
 ## Known gaps
 
 - `leading`/`trailing` are `ReactNode` slots (per the generic-row spec) — the nodes' own contrast
   and touch-target concerns belong to the consumer.
 
-## Performance
+## Motion
 
-Wrapped in `React.memo`; the Pressable style function is `useCallback`'d.
+The non-pressable branch is an `Animated.View` with `FadeInDown.springify()` / `FadeOut` and a
+`LinearTransition` layout preset, all `reduceMotion(ReduceMotion.System)`. The pressable branch
+mounts with no entrance — it is the one a `FlatList` recycles mid-scroll — and animates only its
+press feedback (`usePressState`: scale + a `stateLayerScrim` overlay on the native driver).
 
-## Modernization (v1.0.7)
+## Performance
 
-- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
-- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
-- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.
+Wrapped in `React.memo`; the colours, accessibility name and both root style arrays are `useMemo`'d,
+so nothing is reallocated per render.

package/lib/module/modules/list-screen/ListScreen.js

@@ -0,0 +1,63 @@
+"use strict";
+
+import { memo, useCallback, useMemo } from "react";
+import { VirtualList } from "../../core/list/VirtualList.js";
+import { Divider } from "../divider/index.js";
+import { Screen } from "../screen/index.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+function ListScreenInner({
+  data,
+  renderItem,
+  keyExtractor,
+  itemHeight,
+  refreshing,
+  onRefresh,
+  onEndReached,
+  ListFooterComponent,
+  ListEmptyComponent,
+  appBar,
+  edges,
+  padded,
+  keyboardAvoiding,
+  state,
+  loading,
+  empty,
+  error,
+  style,
+  testID
+}) {
+  const handleEndReached = useCallback(() => {
+    onEndReached?.();
+  }, [onEndReached]);
+  const separator = useMemo(() => () => /*#__PURE__*/_jsx(Divider, {}), []);
+  const listTestId = testID ? `${testID}-list` : undefined;
+  const list = /*#__PURE__*/_jsx(VirtualList, {
+    data: data,
+    renderItem: renderItem,
+    keyExtractor: keyExtractor,
+    itemHeight: itemHeight,
+    refreshing: refreshing,
+    onRefresh: onRefresh,
+    onEndReached: handleEndReached,
+    onEndReachedThreshold: 0.3,
+    ItemSeparatorComponent: separator,
+    ListFooterComponent: ListFooterComponent,
+    ListEmptyComponent: ListEmptyComponent,
+    testID: listTestId
+  });
+  return /*#__PURE__*/_jsx(Screen, {
+    appBar: appBar,
+    edges: edges,
+    padded: padded,
+    keyboardAvoiding: keyboardAvoiding,
+    state: state,
+    loading: loading,
+    empty: empty,
+    error: error,
+    style: style,
+    testID: testID,
+    children: list
+  });
+}
+export const ListScreen = /*#__PURE__*/memo(ListScreenInner);
+//# sourceMappingURL=ListScreen.js.map

package/lib/module/modules/list-screen/ListScreenProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=ListScreenProps.js.map

package/lib/module/modules/list-screen/MODULE.md

@@ -0,0 +1,12 @@
+# list-screen/ — a Screen and VirtualList with pull-to-refresh and paging
+
+`Screen` + `VirtualList` with pull-to-refresh, `Divider` separators, and `onEndReached` (threshold
+`0.3`) — list refresh stays on the list, not `Screen`'s `ScrollView` wrapper.
+
+## Props
+
+Generic over the row type. Own props: `data`, `renderItem`, `keyExtractor` (all required),
+`itemHeight`, `refreshing`, `onRefresh`, `onEndReached`, `ListFooterComponent`,
+`ListEmptyComponent`. The rest are picked straight off `ScreenProps` and forwarded unchanged:
+`appBar`, `edges`, `padded`, `keyboardAvoiding`, `state`, `loading`, `empty`, `error`, `style`,
+`testID`. `testID` seeds `${testID}-list` on the `VirtualList`.

package/lib/module/modules/list-screen/index.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export { ListScreen } from "./ListScreen.js";
+//# sourceMappingURL=index.js.map

package/lib/module/modules/markdown/MODULE.md

@@ -16,7 +16,7 @@ unclosed fence swallows the rest of the input as code.
 | `index.ts` | Public surface: `Markdown`, `MarkdownProps`, `parseMarkdown`, node types. |
 | `__tests__/parseMarkdown.test.ts` | Pure: every block/inline form + malformed-input robustness. |
 | `__tests__/Markdown.test.ts` | Pure: WCAG contrast for text/link/quote roles (all brands × modes). |
-| `__tests__/Markdown.render.test.tsx` | Render: headings, lists, code, link press wiring, and every heading of a 60-section document reaching the tree (the rotor guard — see Performance). |
+| `__tests__/Markdown.render.test.tsx` | Render: headings, lists, code, link press wiring, every heading of a 60-section document reaching the tree (the rotor guard — see Performance), and the block/list-item safety caps (below-cap unchanged, above-cap capped + affordance reveals everything). |
 | `__tests__/Markdown.dom.test.tsx` | Real DOM (`jest.web.config.js`): a `#`/`##`/`###` document renders real `<h1>`/`<h2>`/`<h3>` tags, not three `<h1>`s. |
 
 ## Props
@@ -64,8 +64,9 @@ The parse is `useMemo`'d on `content`; the **render tree** is the other half of
   The cost is bounded by the content: blocks come from parsing one `content` string, which is a
   chat message or a notes body, not an unbounded dataset. If a caller ever does need a virtualized
   document, that is a different component with a different accessibility contract.
+- **Safety caps exist for pathological/misuse input only — they do NOT contradict the above.**
+  `MAX_RENDERED_BLOCKS` (300) and `MAX_LIST_ITEMS` (50, per list block, independent of the block
+  cap) bound a degenerate `content` string; below either cap a document/list renders exactly as
+  before. Above it, a `Button` ("Show full document" / "+N more items") mounts the real, full tree
+  on press — never a re-introduction of windowing, so the rotor contract holds once expanded.
 - Links render through a memo'd `MarkdownLink` so no per-link closure is rebuilt each render.
-
-## Modernization (v1.0.7)
-
-- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.

package/lib/module/modules/markdown/Markdown.js

@@ -7,8 +7,9 @@
  * VirtualizedList is an error in its own right.
  */
 
-import { Fragment, memo, useCallback, useMemo } from "react";
+import { Fragment, memo, useCallback, useMemo, useState } from "react";
 import { Platform, StyleSheet, Text, View } from "react-native";
+import { Button } from "../button/index.js";
 import { HeadingText } from "../../core/heading/index.js";
 import { useTheme } from "../../theme/hooks.js";
 import { markdownBlockquoteStructure, markdownCodeBlockStructure, markdownListRowStructure, markdownListStructure, markdownStructure, resolveMarkdownColors, resolveMarkdownHeading } from "./Markdown.variants.js";
@@ -18,6 +19,17 @@ const MONO_FONT = Platform.select({
   ios: "Menlo",
   default: "monospace"
 });
+
+/**
+ * Safety caps for pathological/misuse input, not windowing (see MODULE.md "Performance") — below
+ * these numbers a document renders exactly as before; above, an affordance mounts the real, full
+ * tree on press, so the WCAG 2.4.1 rotor contract holds once expanded.
+ */
+// Comfortably covers long-form docs/notes (the existing 60-heading test is a fifth of it) while
+// bounding a document of thousands of blocks.
+export const MAX_RENDERED_BLOCKS = 300;
+// Covers realistic checklists/notes lists; bounds a single oversized list regardless of doc length.
+export const MAX_LIST_ITEMS = 50;
 const MarkdownLink = /*#__PURE__*/memo(function MarkdownLink({
   content,
   url,
@@ -75,6 +87,9 @@ const MarkdownBlock = /*#__PURE__*/memo(function MarkdownBlock({
   colors,
   onLinkPress
 }) {
+  // Called unconditionally (rules of hooks) though only the "list" case below reads it.
+  const [itemsExpanded, setItemsExpanded] = useState(false);
+  const expandItems = useCallback(() => setItemsExpanded(true), []);
   switch (block.type) {
     case "heading":
       {
@@ -116,25 +131,35 @@ const MarkdownBlock = /*#__PURE__*/memo(function MarkdownBlock({
         })
       });
     case "list":
-      return /*#__PURE__*/_jsx(View, {
-        style: markdownListStructure(theme),
-        children: block.items.map((item, itemIndex) => /*#__PURE__*/_jsxs(View, {
-          style: markdownListRowStructure(theme),
-          children: [/*#__PURE__*/_jsx(Text, {
-            style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-              fontSize: theme.fontSizes.md,
-              color: colors.listMarker
-            }],
-            children: block.ordered ? `${itemIndex + 1}.` : "•"
-          }), /*#__PURE__*/_jsx(Text, {
-            style: [theme.fontStyleForWeight(theme.fontWeights.regular), styles.listContent, {
-              fontSize: theme.fontSizes.md,
-              color: colors.text
-            }],
-            children: renderInline(item, theme, colors, onLinkPress)
+      {
+        const visibleItems = itemsExpanded || block.items.length <= MAX_LIST_ITEMS ? block.items : block.items.slice(0, MAX_LIST_ITEMS);
+        const hiddenCount = block.items.length - visibleItems.length;
+        return /*#__PURE__*/_jsxs(View, {
+          style: markdownListStructure(theme),
+          children: [visibleItems.map((item, itemIndex) => /*#__PURE__*/_jsxs(View, {
+            style: markdownListRowStructure(theme),
+            children: [/*#__PURE__*/_jsx(Text, {
+              style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
+                fontSize: theme.fontSizes.md,
+                color: colors.listMarker
+              }],
+              children: block.ordered ? `${itemIndex + 1}.` : "•"
+            }), /*#__PURE__*/_jsx(Text, {
+              style: [theme.fontStyleForWeight(theme.fontWeights.regular), styles.listContent, {
+                fontSize: theme.fontSizes.md,
+                color: colors.text
+              }],
+              children: renderInline(item, theme, colors, onLinkPress)
+            })]
+          }, itemIndex)), hiddenCount > 0 && /*#__PURE__*/_jsx(Button, {
+            variant: "link",
+            tone: "neutral",
+            size: "sm",
+            label: `+${hiddenCount} more items`,
+            onPress: expandItems
           })]
-        }, itemIndex))
-      });
+        });
+      }
     default:
       return /*#__PURE__*/_jsx(Text, {
         style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
@@ -155,15 +180,25 @@ export const Markdown = /*#__PURE__*/memo(function Markdown({
   const colors = useMemo(() => resolveMarkdownColors(theme.colors), [theme.colors]);
   const blocks = useMemo(() => parseMarkdown(content), [content]);
   const rootStyle = useMemo(() => [markdownStructure(theme), style], [theme, style]);
-  return /*#__PURE__*/_jsx(View, {
+  const [blocksExpanded, setBlocksExpanded] = useState(false);
+  const expandBlocks = useCallback(() => setBlocksExpanded(true), []);
+  const visibleBlocks = blocksExpanded || blocks.length <= MAX_RENDERED_BLOCKS ? blocks : blocks.slice(0, MAX_RENDERED_BLOCKS);
+  const hiddenBlockCount = blocks.length - visibleBlocks.length;
+  return /*#__PURE__*/_jsxs(View, {
     testID: testID,
     style: rootStyle,
-    children: blocks.map((block, index) => /*#__PURE__*/_jsx(MarkdownBlock, {
+    children: [visibleBlocks.map((block, index) => /*#__PURE__*/_jsx(MarkdownBlock, {
       block: block,
       theme: theme,
       colors: colors,
       onLinkPress: onLinkPress
-    }, `block-${index}-${block.type}`))
+    }, `block-${index}-${block.type}`)), hiddenBlockCount > 0 && /*#__PURE__*/_jsx(Button, {
+      variant: "outline",
+      tone: "neutral",
+      size: "sm",
+      label: `Show full document (${hiddenBlockCount} more)`,
+      onPress: expandBlocks
+    })]
   });
 });
 const styles = StyleSheet.create({

package/lib/module/modules/markdown/Markdown.variants.js

@@ -49,7 +49,8 @@ export const markdownStructure = createThemedVariants(theme => ({
 }));
 export const markdownCodeBlockStructure = createThemedVariants(theme => ({
   base: {
-    borderRadius: theme.radii.base,
+    borderRadius: theme.radii.md,
+    borderCurve: "continuous",
     padding: theme.space[3]
   }
 }));

package/lib/module/modules/markdown/MarkdownProps.js

@@ -0,0 +1,4 @@
+"use strict";
+
+export {};
+//# sourceMappingURL=MarkdownProps.js.map

package/lib/module/modules/menu/MODULE.md

@@ -16,12 +16,13 @@ own, not a dependency on the `Modal` component.
 
 | File | Role |
 |------|------|
-| `Menu.tsx` | The component. `cloneElement` trigger composition, `Modal` + backdrop + row list, open/close state. Rows are a plain `.map()` inside a `ScrollView` (built only while `open`) — action menus are short lists, so `FlatList`'s VirtualizedList setup on every open was measurable open-time cost with no windowing benefit at current call sites; `ScrollView` keeps the sheet's `maxHeight: 320` scrollable for a list that doesn't fit, without that per-open setup cost. |
+| `Menu.tsx` | The component. `cloneElement` trigger composition, `Modal` + backdrop + row list, open/close state. Under `VIRTUALIZE_THRESHOLD` (15) items the rows are a plain `.map()` inside a `ScrollView`; at or above it they render through `core/list`'s `VirtualList`. |
 | `Menu.variants.ts` | Pure resolvers (`resolveMenuItemColor`, `resolveMenuRowPressedBackground`) + the themed structural resolvers (`menuOverlayStructure`, `menuSheetStructure`, `menuRowStructure`). No React, no lucide. |
 | `index.ts` | Public surface: `Menu`, `MenuProps`, `MenuItem`, `MenuTriggerProps`, `MenuItemTone`, `IconName` (re-exported from `core/icon`). |
 | `__tests__/Menu.test.ts` | Pure: WCAG contrast (all brands × modes) + touch target + the tone→role mapping. |
 | `__tests__/Menu.render.test.tsx` | Render: open/close, trigger `onPress` chaining, disabled gating, item selection, backdrop dismiss, the sheet's menu/modal semantics on BOTH paths, and the web-portal opt-in branch (mocking `renderWebPortal`). |
 | `__tests__/Menu.keyboard.test.tsx` | Web keyboard: roving tabindex, arrows/Home/End/typeahead, Space activation, Escape. Routes the mocked helpers into the real `keyboard.web` implementation. |
+| `__tests__/Menu.perf.test.tsx` | Open-time cost of the `ScrollView` branch against a `VirtualizedList` one. |
 | `__tests__/Menu.motion.test.tsx` | Reduce motion (WCAG 2.3.3), both halves: motion off → the sheet opens already at rest with no `Animated.timing` and `animationType="none"`; motion on → it really tweens from the entrance transform (forcing Animated's JS driver, since a native-driven value never advances under Jest). |
 
 ## Props
@@ -50,7 +51,7 @@ row size, since an action list's row height isn't a caller-facing choice.
   and without this the whole page behind the menu stayed in the accessibility tree and reachable by
   swipe on web.
 - **1.4.3** — every row's label is measured ≥ 4.5:1 against the sheet fill (`bg.surface`), for both
-  `default` (`fg.default`) and `danger` (`status.danger.text`) tones, across all 8 brands × both
+  `default` (`fg.default`) and `danger` (`status.danger.text`) tones, across all 9 brands × both
   modes.
 - **1.4.11** — the row icon reuses the label's exact colour (never a separate lookup): since the
   label already clears the stricter 4.5:1 text minimum, the icon clears its looser 3:1 non-text
@@ -61,6 +62,7 @@ row size, since an action list's row height isn't a caller-facing choice.
   menu row is never icon-only.
 - **2.3.3** — the menu's `animationType` is `"none"` instead of `"fade"` when `useReducedMotion()`
   is true, and the sheet's own scale/lift `setValue`s straight to rest (`Menu.motion.test.tsx`).
+  Row presses use `usePressState` (scale + state-layer overlay).
 - Backdrop press closes the menu without calling any item's `onPress` — dismissal and selection are
   two distinct code paths (`closeMenu` vs. `selectItem`), so a stray tap can never accidentally fire
   an action.
@@ -125,10 +127,12 @@ supplied per row by `useSpaceActivation` (RNW's `isValidKeyPress` needs a `butto
 
 ## Performance
 
-Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `openMenu`/`closeMenu` are `useCallback`'d, and the inline `onPress` previously injected into the caller-supplied `trigger` via `cloneElement` on every render is extracted to `handleTriggerPress` (`useCallback`, deps `[trigger, openMenu]`) — `trigger` is a consumer-supplied child (typically this library's own `Button`), so a fresh callback there would defeat its memo. `selectItem` and the per-row `onPress` stay inline: they go to `Pressable`/`Icon` (host elements / primitive props), not a memoized child. The sheet subtree (backdrop + rows) is built only while `open` — a closed menu mounts nothing beyond the trigger. Rows are rendered with a plain `.map()` inside a `ScrollView` (not `FlatList`): action menus are short, and mounting a fresh `VirtualizedList` on the same commit as the modal fade-in was measurable open-time cost (~2× p50 in a Jest open benchmark for a 2-item list) with no windowing benefit at current call sites — `ScrollView` has no such per-open setup and still lets a list taller than the sheet's `maxHeight: 320` scroll, which a bare `.map()` with no scroll container would silently lose. Rows get `bg.sunken` press feedback (`resolveMenuRowPressedBackground`, same non-`bg.hover` reasoning as `RadioGroup`/`Accordion`), measured in `Menu.test.ts`.
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). `openMenu`/`closeMenu` are `useCallback`'d, and the inline `onPress` previously injected into the caller-supplied `trigger` via `cloneElement` on every render is extracted to `handleTriggerPress` (`useCallback`, deps `[trigger, openMenu]`) — `trigger` is a consumer-supplied child (typically this library's own `Button`), so a fresh callback there would defeat its memo. `selectItem` and the per-row `onPress` stay inline: they go to `Pressable`/`Icon` (host elements / primitive props), not a memoized child. The sheet subtree (backdrop + rows) is built only while `open` — a closed menu mounts nothing beyond the trigger. Below `VIRTUALIZE_THRESHOLD` (15) items rows are a plain `.map()` inside a `ScrollView`, not a `FlatList`: mounting a fresh `VirtualizedList` on the same commit as the modal fade-in was measurable open-time cost (~2× p50 in a Jest open benchmark for a 2-item list) with no windowing benefit at that size, and `ScrollView` still lets a list taller than the sheet's `maxHeight: 320` scroll, which a bare `.map()` would silently lose. At or above the threshold the cost flips and `VirtualList` takes over — which is where the End-key gap below comes from. Rows get `bg.sunken` press feedback (`resolveMenuRowPressedBackground`, same non-`bg.hover` reasoning as `RadioGroup`/`Accordion`), measured in `Menu.test.ts`.
 
-## Modernization (v1.0.7)
+## Motion
 
-- Theme imports decoupled to `theme/hooks`; optional peers (reanimated, gesture-handler, flash-list) load at runtime.
-- List-heavy surfaces use `VirtualList` with device-tier window sizing where applicable.
-- `React.memo` + stable callbacks retained; render-item/key-extractor hoisted per ESLint perf rules.
+No per-row entrance. `enter` (`core/motion`) drives the sheet's scale/lift/opacity and the
+backdrop's fade together. The web-portal path (no RN `<Modal>`) stays `mounted` through a real timed
+exit; the RNModal path is gated on `open` directly, since RN's own `animationType` owns that
+surface's exit. `BACKDROP_SCRIM` takes its opacity from the shared `MOTION_TRANSFORM.scrimOpacity`,
+matching Modal/Drawer/BottomSheet; the row press overlay uses `stateLayerScrim`.