pixelize-native-library 1.0.7 → 1.2.0

package/lib/module/modules/limit-reached-modal/MODULE.md

@@ -0,0 +1,94 @@
+# limit-reached-modal/ — a plan-limit dialog composed from Modal + Button
+
+`LimitReachedModal` is the mobile counterpart to web's `LimitReachedModal`
+(`Micro-Components/src/Components/LimitReachedModal`) — a dialog shown when an org hits a plan
+limit (records, automations, custom modules, seats, projects, tickets). Like `AlertDialog`, it is
+DELIBERATELY built by composing this library's own, already-shipped `Modal` (backdrop, panel,
+dismissal, title contrast) and `Button` (tone, press feedback, touch target) rather than
+reimplementing either. This module owns exactly its own copy (six `kind`s × admin/member), the
+optional usage line, and which action(s) appear.
+
+## Files
+
+| File | Role |
+|------|------|
+| `LimitReachedModal.tsx` | The component. Composes `Modal` (title, dismissal) with an icon badge, a message, an optional usage line, and a one- or two-`Button` action row. |
+| `LimitReachedModal.variants.ts` | Pure resolvers: the `LimitKind` copy table (`resolveLimitReachedCopy`, ported verbatim from web), `formatLimitUsage`, and the themed icon-badge/action-row layout + colour (`resolveLimitReachedModalColors`). No React, no lucide. |
+| `index.ts` | Public surface: `LimitReachedModal`, `LimitReachedModalProps`, `LimitKind`. |
+| `__tests__/LimitReachedModal.test.ts` | Pure: the copy resolver for all six kinds × both admin/member paths, the usage formatter, and WCAG contrast for this module's own colour choices (icon badge, message, usage) — measured for all 9 brands × both modes. |
+| `__tests__/LimitReachedModal.render.test.tsx` | Render: hidden when `visible=false`, the upgrade CTA absent when `canManageBilling=false`, `onUpgrade`/`onRequestClose` wiring, and the usage line appearing only when both `limit` and `used` are given. |
+
+## Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `visible` | `boolean` | — | Required. Forwarded to `Modal` — fully controlled, no internal open state. |
+| `onRequestClose` | `() => void` | — | Required. Forwarded to `Modal` (backdrop press, Android back, iOS VoiceOver escape). Also the dismiss action's `onPress`. |
+| `kind` | `LimitKind` | — | Required. `"record" \| "automation" \| "custom_modules" \| "user" \| "projects" \| "tickets"` — selects the copy table entry. |
+| `limit` | `number \| null` | `null` | Plan limit for `kind`. Paired with `used` to show `"<used> of <limit> <unit> used"`. |
+| `used` | `number \| null` | `null` | Current usage for `kind`. Either alone renders no usage line — both are required together. |
+| `canManageBilling` | `boolean` | — | Required. `true` shows the admin copy + an "Upgrade plan" CTA; `false` shows "contact your organization administrator" copy and no CTA. |
+| `onUpgrade` | `() => void` | — | Optional. Wired to the upgrade Button's `onPress` (only rendered when `canManageBilling`). |
+| `title` | `string` | `kind`'s default | Overrides the resolved title, forwarded to `Modal`'s `title`. |
+| `message` | `string` | `kind`'s default | Overrides the resolved admin/member message. |
+| `testID` | `string` | — | Forwarded to `Modal` (seeds `${testID}-backdrop`/`${testID}-panel`) and also seeds `${testID}-dismiss` / `${testID}-upgrade` on the two actions. |
+
+No `style` — same reasoning as `Modal`/`AlertDialog`: there is no parent layout flow to place a
+full-screen dialog within.
+
+## Accessibility contract
+
+- **1.4.3** — the title (via `Modal`'s own `resolveModalPanelColors`) and the message (`fg.default`
+  on the panel's `bg.surface`) clear 4.5:1 for every brand × mode.
+- **1.4.3** — the usage line (`fg.muted` on `bg.surface`) clears 4.5:1 — the same pairing
+  `AlertDialog`'s description proves for itself.
+- **1.4.3** — the icon glyph (`status.warning.text` on its own `status.warning.subtle` badge fill)
+  clears 4.5:1 — the exact pairing Badge/Banner's own `subtle` variant already proves at the role
+  layer (`roleColors.test.ts`), reused rather than freshly measured.
+- **Dismissal semantics** — every one of `Modal`'s dismissal paths (backdrop press, Android hardware
+  back, iOS VoiceOver escape, and on web Escape) resolves to `onRequestClose`, since this module
+  never intercepts it — same contract as the dismiss action itself.
+- **2.1.1 keyboard (web only)** — INHERITED whole from `Modal`. This matters most at
+  `canManageBilling: false`, which renders a single "Close" button: on the `ModalPortalProvider`
+  branch, before that fix, one Tab put a keyboard user outside the dialog behind the scrim with no
+  way back to the only control that dismisses it. No keyboard code lives here;
+  `__tests__/LimitReachedModal.keyboard.web.test.tsx` asserts the inheritance.
+- **Upgrade vs. dismiss are never confusable** — the dismiss action is always `variant="outline"`
+  (unfilled) and the upgrade action is always `variant="solid"` (filled, high-emphasis), so the
+  primary choice is never the visually quieter one.
+
+## Patterns
+
+1. **Compose, don't reimplement.** `Modal` and `Button` are stable, shipped modules; no backdrop,
+   panel, or press-feedback logic is duplicated here — the same "compose existing exports" step
+   `AlertDialog` and `EmptyState` already take.
+2. **A fixed severity, not a `tone` prop.** A plan limit is a soft stop, not a destructive action —
+   the icon badge is always `status.warning`, so there is nothing here to widen into a raw
+   `color?: string`.
+3. **No gradient, no per-`kind` icon.** Web's header uses a brand gradient and swaps `Crown`/`Users`
+   per `kind`; this library has no `LinearGradient` and no registered `crown` glyph, and the API
+   contract bans a raw colour prop regardless. One `triangle-alert` icon on `status.warning` reads
+   correctly for every kind and every brand — the same icon `Banner` already resolves for its own
+   `warning` tone (`resolveBannerIcon`).
+4. **Structure vs. colour split**, even for a thin composing module — the icon badge and action row
+   layouts live in themed resolvers; colour is `resolveLimitReachedModalColors`, applied inline.
+
+## Known gaps
+
+- No built-in scrolling for a long message/usage combination on a small screen — same known gap
+  `Modal`/`AlertDialog` document for `children` in general.
+- No per-`kind` icon or illustration (see Patterns #3) — every `kind` shares one `triangle-alert`
+  badge. A future kind needing a distinct glyph adds one via `core/icon`'s deep-import + map-entry
+  pattern, not a per-kind override prop.
+
+## Performance
+
+Wrapped in `React.memo` (repo-wide re-render audit, 2026-07-17 — see root `CLAUDE.md`). The inline
+`() => onUpgrade?.()` is a fresh closure per render, same as `EmptyState`'s action Button — cheap
+because it forwards straight to a leaf `Pressable`, never a memoized child list item.
+
+## Modernization (v1.0.7)
+
+- 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.

package/lib/module/modules/limit-reached-modal/index.js

@@ -0,0 +1,11 @@
+"use strict";
+
+/**
+ * Public surface of `pixelize-native-library/limit-reached-modal`. Value exports and type exports
+ * are split for `verbatimModuleSyntax`. The copy table, usage formatter, and colour/structure
+ * resolvers stay internal — a consumer configures a LimitReachedModal through its props, never by
+ * importing its internals.
+ */
+
+export { LimitReachedModal } from "./LimitReachedModal.js";
+//# sourceMappingURL=index.js.map

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

@@ -1,10 +1,19 @@
 "use strict";
 
-import { memo, useCallback } from "react";
-import { Pressable, Text, View } from "react-native";
-import { useTheme } from "../../theme/index.js";
+/**
+ * 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.
+ */
+
+import { memo, useMemo } from "react";
+import { Animated, Pressable, Text, View } from "react-native";
+import { usePressMotion } from "../../core/motion/index.js";
+import { useTheme } from "../../theme/hooks.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);
 export const ListItem = /*#__PURE__*/memo(function ListItem({
   leading,
   title,
@@ -16,59 +25,67 @@ export const ListItem = /*#__PURE__*/memo(function ListItem({
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveListItemColors(theme.colors, unread);
-  const a11y = resolveListItemAccessibility({
+  const pressable = onPress !== undefined;
+  const press = usePressMotion(!pressable);
+  const colors = useMemo(() => resolveListItemColors(theme.colors, unread), [theme.colors, unread]);
+  const a11y = useMemo(() => resolveListItemAccessibility({
     title,
     subtitle,
     unread
-  });
-  const rootStyle = useCallback(({
-    pressed
-  }) => [listItemStructure(theme), {
-    backgroundColor: pressed ? colors.pressed : colors.background
+  }), [title, subtitle, unread]);
+  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]);
+  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), {
+    fontSize: theme.fontSizes.sm,
+    color: colors.subtitle
+  }], [theme, colors]);
   const body = /*#__PURE__*/_jsxs(_Fragment, {
     children: [unread && /*#__PURE__*/_jsx(View, {
       testID: testID === undefined ? undefined : `${testID}-dot`,
       accessibilityElementsHidden: true,
       importantForAccessibility: "no-hide-descendants",
-      style: [listItemDotStructure(theme), {
-        backgroundColor: colors.dot
-      }]
+      style: dotStyle
     }), leading, /*#__PURE__*/_jsxs(View, {
-      style: listItemBodyStructure(theme),
+      style: bodyStyle,
       children: [/*#__PURE__*/_jsx(Text, {
         numberOfLines: 1,
-        style: [theme.fontStyleForWeight(unread ? theme.fontWeights.semibold : theme.fontWeights.medium), {
-          fontSize: theme.fontSizes.md,
-          color: colors.title
-        }],
+        style: titleStyle,
         children: title
       }), subtitle !== undefined && /*#__PURE__*/_jsx(Text, {
         numberOfLines: 2,
-        style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
-          fontSize: theme.fontSizes.sm,
-          color: colors.subtitle
-        }],
+        style: subtitleStyle,
         children: subtitle
       })]
     }), trailing]
   });
-  if (onPress === undefined) {
+  if (!pressable) {
     return /*#__PURE__*/_jsx(View, {
       testID: testID,
-      style: [listItemStructure(theme), {
-        backgroundColor: colors.background
-      }, style],
+      style: baseStyle,
       children: body
     });
   }
-  return /*#__PURE__*/_jsx(Pressable, {
+  return /*#__PURE__*/_jsx(AnimatedPressable, {
     testID: testID,
     accessibilityRole: "button",
     accessibilityLabel: a11y.accessibilityLabel,
     onPress: onPress,
-    style: rootStyle,
+    onPressIn: press.onPressIn,
+    onPressOut: press.onPressOut,
+    style: pressableStyle,
     children: body
   });
 });

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

@@ -45,3 +45,9 @@ a plain `View` otherwise.
 ## Performance
 
 Wrapped in `React.memo`; the Pressable style function is `useCallback`'d.
+
+## Modernization (v1.0.7)
+
+- 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.

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

@@ -1,7 +1,7 @@
 # markdown/ — a dependency-free markdown renderer
 
 `Markdown` parses and renders a markdown string with a small hand-rolled parser — no third-party
-markdown/renderer dependency. Supported: h1–h3, bold, italic, inline code, fenced code blocks
+markdown/renderer dependency. Supported: h1–h6, bold, italic, inline code, fenced code blocks
 (monospace block on a `bg.sunken` fill, no copy button), unordered/ordered lists, links,
 blockquotes, paragraphs. The parser never throws: malformed input degrades to literal text, an
 unclosed fence swallows the rest of the input as code.
@@ -16,7 +16,8 @@ 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. |
+| `__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.dom.test.tsx` | Real DOM (`jest.web.config.js`): a `#`/`##`/`###` document renders real `<h1>`/`<h2>`/`<h3>` tags, not three `<h1>`s. |
 
 ## Props
 
@@ -31,8 +32,12 @@ unclosed fence swallows the rest of the input as code.
 
 Body/list text `fg.default`, blockquote `fg.muted` behind a `border.default` left rule
 (decorative, Divider's reasoning), code on `bg.sunken`, links `accent.text` + underline
-(`link` a11y role), headings `2xl bold` / `xl semibold` / `lg semibold` with the `header` a11y
-role. Monospace is the platform face (Menlo/monospace) — the token layer has no mono family.
+(`link` a11y role), headings `2xl bold` (h1) / `xl semibold` (h2) / `lg semibold` (h3+) with the
+`header` a11y role. **`aria-level` carries the real `#`-count (1–6), no longer clamped to 3** — a
+`react-native-web` heading with no `aria-level` renders `<h1>` regardless of role, so every heading
+used to collapse to the same DOM tag (see `core/heading/MODULE.md`). Levels 4–6 share level 3's
+type size — the document's *structure* is what the level communicates below `lg`. Monospace is the
+platform face (Menlo/monospace) — the token layer has no mono family.
 
 ## Known gaps
 
@@ -41,4 +46,26 @@ role. Monospace is the platform face (Menlo/monospace) — the token layer has n
 
 ## Performance
 
-Wrapped in `React.memo`; the parse is `useMemo`'d on `content`.
+The parse is `useMemo`'d on `content`; the **render tree** is the other half of the cost, so:
+
+- Each block renders through `MarkdownBlock`, a `React.memo`'d component. Its props (`theme`,
+  `colors`, `onLinkPress`, and the block node itself) are stable while `content` is unchanged, so a
+  parent re-render re-renders no block.
+- `colors` is `useMemo`'d on `theme.colors`; the root style array is `useMemo`'d on `(theme, style)`.
+- **A document is never virtualized.** Every block renders, always — a plain `.map()`, no
+  `VirtualList`, no block-count threshold. Two reasons, and the first is not a performance
+  trade-off:
+  1. **The heading outline is the document's navigation.** A screen reader's rotor lists the
+     `accessibilityRole="header"` nodes that are *in the tree*; windowing leaves ~10 blocks mounted,
+     so a 60-heading document offered a rotor a handful of entries and no way to reach the rest
+     (WCAG 2.4.1). Unlike a list of records, a document's own structure is the affordance.
+  2. `Markdown` is normally embedded in a caller's `ScrollView`, where a nested VirtualizedList is
+     an error in React Native regardless.
+  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.
+- 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

@@ -1,8 +1,16 @@
 "use strict";
 
-import { Fragment, memo, useMemo } from "react";
+/**
+ * A markdown document is rendered whole, never virtualized: the heading outline is what a screen
+ * reader's rotor navigates, and windowing would expose only the ~10 blocks currently on screen
+ * (WCAG 2.4.1). It is also normally embedded in a caller's ScrollView, where a nested
+ * VirtualizedList is an error in its own right.
+ */
+
+import { Fragment, memo, useCallback, useMemo } from "react";
 import { Platform, StyleSheet, Text, View } from "react-native";
-import { useTheme } from "../../theme/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";
 import { parseMarkdown } from "./parseMarkdown.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -10,6 +18,22 @@ const MONO_FONT = Platform.select({
   ios: "Menlo",
   default: "monospace"
 });
+const MarkdownLink = /*#__PURE__*/memo(function MarkdownLink({
+  content,
+  url,
+  color,
+  onLinkPress
+}) {
+  const handlePress = useCallback(() => onLinkPress?.(url), [onLinkPress, url]);
+  return /*#__PURE__*/_jsx(Text, {
+    accessibilityRole: "link",
+    onPress: onLinkPress === undefined ? undefined : handlePress,
+    style: [styles.link, {
+      color
+    }],
+    children: content
+  });
+});
 function renderInline(nodes, theme, colors, onLinkPress) {
   return nodes.map((node, index) => {
     switch (node.type) {
@@ -32,13 +56,11 @@ function renderInline(nodes, theme, colors, onLinkPress) {
           children: node.content
         }, index);
       case "link":
-        return /*#__PURE__*/_jsx(Text, {
-          accessibilityRole: "link",
-          onPress: onLinkPress === undefined ? undefined : () => onLinkPress(node.url),
-          style: [styles.link, {
-            color: colors.link
-          }],
-          children: node.content
+        return /*#__PURE__*/_jsx(MarkdownLink, {
+          content: node.content,
+          url: node.url,
+          color: colors.link,
+          onLinkPress: onLinkPress
         }, index);
       default:
         return /*#__PURE__*/_jsx(Fragment, {
@@ -47,19 +69,25 @@ function renderInline(nodes, theme, colors, onLinkPress) {
     }
   });
 }
-function renderBlock(block, index, theme, colors, onLinkPress) {
+const MarkdownBlock = /*#__PURE__*/memo(function MarkdownBlock({
+  block,
+  theme,
+  colors,
+  onLinkPress
+}) {
   switch (block.type) {
     case "heading":
       {
         const spec = resolveMarkdownHeading(theme, block.level);
-        return /*#__PURE__*/_jsx(Text, {
+        return /*#__PURE__*/_jsx(HeadingText, {
           accessibilityRole: "header",
+          "aria-level": block.level,
           style: [theme.fontStyleForWeight(theme.fontWeights[spec.fontWeight]), {
             fontSize: spec.fontSize,
             color: colors.heading
           }],
           children: renderInline(block.children, theme, colors, onLinkPress)
-        }, index);
+        });
       }
     case "code-block":
       return /*#__PURE__*/_jsx(View, {
@@ -73,7 +101,7 @@ function renderBlock(block, index, theme, colors, onLinkPress) {
           }],
           children: block.content
         })
-      }, index);
+      });
     case "blockquote":
       return /*#__PURE__*/_jsx(View, {
         style: [markdownBlockquoteStructure(theme), {
@@ -86,7 +114,7 @@ function renderBlock(block, index, theme, colors, onLinkPress) {
           }],
           children: renderInline(block.children, theme, colors, onLinkPress)
         })
-      }, index);
+      });
     case "list":
       return /*#__PURE__*/_jsx(View, {
         style: markdownListStructure(theme),
@@ -106,7 +134,7 @@ function renderBlock(block, index, theme, colors, onLinkPress) {
             children: renderInline(item, theme, colors, onLinkPress)
           })]
         }, itemIndex))
-      }, index);
+      });
     default:
       return /*#__PURE__*/_jsx(Text, {
         style: [theme.fontStyleForWeight(theme.fontWeights.regular), {
@@ -114,9 +142,9 @@ function renderBlock(block, index, theme, colors, onLinkPress) {
           color: colors.text
         }],
         children: renderInline(block.children, theme, colors, onLinkPress)
-      }, index);
+      });
   }
-}
+});
 export const Markdown = /*#__PURE__*/memo(function Markdown({
   content,
   onLinkPress,
@@ -124,12 +152,18 @@ export const Markdown = /*#__PURE__*/memo(function Markdown({
   testID
 }) {
   const theme = useTheme();
-  const colors = resolveMarkdownColors(theme.colors);
+  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, {
     testID: testID,
-    style: [markdownStructure(theme), style],
-    children: blocks.map((block, index) => renderBlock(block, index, theme, colors, onLinkPress))
+    style: rootStyle,
+    children: blocks.map((block, index) => /*#__PURE__*/_jsx(MarkdownBlock, {
+      block: block,
+      theme: theme,
+      colors: colors,
+      onLinkPress: onLinkPress
+    }, `block-${index}-${block.type}`))
   });
 });
 const styles = StyleSheet.create({

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

@@ -18,6 +18,11 @@ export function resolveMarkdownColors(colors) {
     listMarker: colors.fg.muted
   };
 }
+/**
+ * SIZE only — `h4`–`h6` deliberately share `h3`'s size while keeping their own `aria-level`. The
+ * document's structure is what the heading level carries; three more type sizes below `lg` would
+ * be smaller than body text.
+ */
 export function resolveMarkdownHeading(theme, level) {
   switch (level) {
     case 1:
@@ -30,7 +35,7 @@ export function resolveMarkdownHeading(theme, level) {
         fontSize: theme.fontSizes.xl,
         fontWeight: "semibold"
       };
-    case 3:
+    default:
       return {
         fontSize: theme.fontSizes.lg,
         fontWeight: "semibold"

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

@@ -2,11 +2,11 @@
 
 /**
  * A small hand-rolled markdown parser — no dependencies, never throws. Supports the subset the
- * renderer draws: h1–h3, bold, italic, inline code, fenced code blocks, unordered/ordered lists,
+ * renderer draws: h1–h6, bold, italic, inline code, fenced code blocks, unordered/ordered lists,
  * links, blockquotes, paragraphs. Anything malformed degrades to literal text.
  */
 
-const HEADING_RE = /^(#{1,3})\s+(.*)$/;
+const HEADING_RE = /^(#{1,6})\s+(.*)$/;
 const UNORDERED_RE = /^\s*[-*+]\s+(.*)$/;
 const ORDERED_RE = /^\s*\d+[.)]\s+(.*)$/;
 const BLOCKQUOTE_RE = /^\s*>\s?(.*)$/;
@@ -84,7 +84,7 @@ function parseBlocks(content) {
     const heading = HEADING_RE.exec(line);
     if (heading !== null) {
       flushParagraph();
-      const level = Math.min((heading[1] ?? "#").length, 3);
+      const level = (heading[1] ?? "#").length;
       blocks.push({
         type: "heading",
         level,

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

@@ -16,11 +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. |
-| `Menu.variants.ts` | Pure resolver (`resolveMenuItemColor`) + the themed structural resolvers (`menuOverlayStructure`, `menuSheetStructure`, `menuRowStructure`). No React, no lucide. |
+| `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.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, and the web-portal opt-in branch (mocking `renderWebPortal`). |
+| `__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.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
 
@@ -29,7 +31,7 @@ own, not a dependency on the `Modal` component.
 | `trigger` | `ReactElement<MenuTriggerProps>` | — | Required. A single element accepting `onPress` (e.g. a `Button`). Cloned to chain its `onPress` with opening the menu. |
 | `items` | `{ label: string; icon?: IconName; onPress: () => void; tone?: "default" \| "danger" }[]` | — | Required. Rendered in order; `danger` renders the row in `status.danger.text`. |
 | `disabled` | `boolean` | `false` | Blocks the menu from opening. Does **not** restyle the trigger — see "Design decisions" below. |
-| `testID` | `string` | — | Seeds `${testID}-backdrop` and `${testID}-item-${index}`. Not applied to the trigger — the trigger owns its own `testID`. |
+| `testID` | `string` | — | Seeds `${testID}-backdrop`, `${testID}-sheet` and `${testID}-item-${index}`. Not applied to the trigger — the trigger owns its own `testID`. |
 
 No `style` prop — like Tooltip, Menu renders no sized node of its own for an app to place; the
 trigger keeps whatever layout it already has. `variant`/`size` are also absent: Menu has one fixed
@@ -37,8 +39,16 @@ row size, since an action list's row height isn't a caller-facing choice.
 
 ## Accessibility contract (WCAG)
 
-- **4.1.2 / semantics** — every row is `accessibilityRole="menuitem"`. The backdrop is
-  `accessible={false}` (same as Select's) so it isn't announced as a separate focusable element.
+- **4.1.2 / semantics** — the sheet carries `accessibilityRole="menu"`, the container role its
+  `accessibilityRole="menuitem"` rows need (rows without one are announced as loose menu items with
+  no menu). The backdrop is `accessible={false}` (same as Select's) so it isn't announced as a
+  separate focusable element.
+- **4.1.2 / modal semantics** — the sheet also carries `accessibilityViewIsModal` +
+  `onAccessibilityEscape={closeMenu}`, the pair `Modal.tsx` establishes for its own panel. Both are
+  set on the sheet node itself, BEFORE the portal branch, so they apply on **both** paths: RN's own
+  `<Modal>` presents a separate native surface, but the web-portal path renders no `<Modal>` at all,
+  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
   modes.
@@ -50,7 +60,7 @@ row size, since an action list's row height isn't a caller-facing choice.
 - **Icon-only rule (rule 5) does not apply** — every row always renders a visible `label` text; a
   menu row is never icon-only.
 - **2.3.3** — the menu's `animationType` is `"none"` instead of `"fade"` when `useReducedMotion()`
-  is true.
+  is true, and the sheet's own scale/lift `setValue`s straight to rest (`Menu.motion.test.tsx`).
 - 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.
@@ -66,8 +76,7 @@ row size, since an action list's row height isn't a caller-facing choice.
    `onLongPress`/`onPressOut` injection).
 4. **RN's own `Modal`, not this library's** — same reasoning as Select: a quick transient overlay,
    not a persistent app dialog with a title/children contract.
-5. **Closed `tone` union** — `default | danger`, resolved from role colours, never a free-form
-   `color` prop.
+5. **Closed `tone` union** — `default | danger`, resolved from role colours, never a free-form `color` prop.
 
 ## Design decisions specific to this module
 
@@ -89,15 +98,37 @@ row size, since an action list's row height isn't a caller-facing choice.
   `Popover`-style module with real anchor measurement would be the place to fix this, not a prop
   added here — the same deferral Tooltip's own docs make for its unmeasured bubble placement.
 
+## Keyboard (web)
+
+Wired to `core/a11y/keyboard` (all no-ops on native). The item list is **one tab stop**: exactly one
+row carries `tabIndex={0}` (`focusItemProps`) and the arrows / Home / End / typeahead move it
+(`useRovingKeys` on the sheet, capture phase). Each row focuses itself when it becomes the active
+one — the tabindex alone only names the tab stop, and `useFocusTrap` needs the focused node to still
+be tabbable or Tab escapes the menu. `useFocusTrap` also restores focus to the trigger on close, and
+`useDismissOnEscape` closes on Escape.
+
+**`useRovingKeys` gets no `onActivate`.** RNW already presses a `menuitem` on Enter, and Space is
+supplied per row by `useSpaceActivation` (RNW's `isValidKeyPress` needs a `button` tag/role, which
+`menuitem` deliberately is not) — passing `onActivate` too would run the item twice.
+
 ## Known gaps
 
 - No measured anchor position (see above) — the sheet always centers, regardless of where the
   trigger sits on screen.
-- No submenu / nested items — v1 is a single flat action list, matching the spec this module was
-  built against.
-- No keyboard/arrow-key navigation between rows (touch-only interaction model, same scope as
-  Select's option list).
+- **No SCREEN-READER focus trap on Android.** Tab is trapped on web (`useFocusTrap`) and the sheet
+  declares `accessibilityViewIsModal`, which iOS VoiceOver honours; Android has no sibling-hiding
+  equivalent and relies on RN's own `<Modal>` surface instead. Same gap `Modal`'s own docs record.
+- No submenu / nested items — v1 is a single flat action list.
+- **Arrowing past the mounted window does not scroll.** `core/list` exposes no imperative handle,
+  so with `items.length >= 15` (the `VirtualList` branch) End can name an item the list has not
+  mounted, and focus stays put. Fixing it needs a `scrollToIndex` on `core/list`.
 
 ## 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.
+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`.
+
+## Modernization (v1.0.7)
+
+- 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.