@krapwoo/ds-viewer 0.14.2 → 0.15.0

package/native/catalog/GroupPage.tsx

@@ -0,0 +1,230 @@
+import React, { useEffect, useMemo, useRef } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { CATALOG_SPACE } from './tokens';
+import type { SectionPager } from './SectionBlock';
+import { hashForId } from './catalogNavigation';
+import { referenceLinkProps, type ReferenceNavigation } from './catalogReferences';
+import { JumpRow, type JumpItem } from './JumpRow';
+import { AnatomyBox, FamilyPageHead, FamilyPart, MemberPanelHost, PartOfLine, PartTreeBranch, scrollAndFocusMember, type FamilyMember } from './FamilyPage';
+import { buildPartTree } from './familyModel';
+import type { CatalogAnatomy, FamilyDef, PreviewWidths, SectionDef } from './types';
+
+/** #63 R2: the same "resolve, then build a real link" `FamilyPage.tsx`'s own module-private
+ *  `familyLink` already implements for a same-family member address — duplicated here as a small
+ *  function (rather than exporting that private helper) since a group page's own jump chip is the
+ *  only call site that needs it outside that file. */
+function memberLink(
+  navigation: ReferenceNavigation | undefined,
+  resolvesAddress: (name: string) => boolean,
+  memberId: string,
+): { href: string; onPress?: (event?: { preventDefault?: () => void }) => void } | undefined {
+  if (navigation) {
+    const activation = referenceLinkProps(navigation, memberId);
+    return activation ? { href: hashForId(activation.memberId ?? activation.pageId), onPress: activation.onPress } : undefined;
+  }
+  return resolvesAddress(memberId) ? { href: hashForId(memberId) } : undefined;
+}
+
+type GroupMember = FamilyMember & { partOf?: { pageId: string; title: string; number: string }; anatomy?: CatalogAnatomy };
+
+/** #63 R2: one top-level member's own section — its name row/specimens/disclosure (`FamilyPart`,
+ *  unnumbered, the same piece a family's own Related member uses), its own "Part N of <Family>"
+ *  link when it's an external part, its own embedded-family anatomy box (if any), and its own
+ *  parts nested underneath (the same `PartTreeBranch` tree a family's Parts section renders). Its
+ *  own component (rather than inline in `GroupPage`'s own `.map()`) so its tree-line `pinNodesRef`
+ *  is a fresh hook per member, the same reason `FamilySectionGroup` is its own component in
+ *  `FamilyPage.tsx`. */
+function GroupTopLevelMember({
+  member, byId, outline, descendantIds, allMemberIds, defaultPreviewWidths, apiLabel, resolvesAddress, navigation, registerNode,
+}: {
+  member: GroupMember;
+  byId: ReadonlyMap<string, FamilyMember>;
+  outline: FamilyDef['outline'];
+  /** Every one of this member's own descendants on the page (not only its direct children) — the
+   *  same full-subtree input `buildPartTree` expects (`FamilySectionGroup`'s own precedent). */
+  descendantIds: readonly string[];
+  allMemberIds: readonly string[];
+  defaultPreviewWidths?: PreviewWidths;
+  apiLabel: string;
+  resolvesAddress: (name: string) => boolean;
+  navigation?: ReferenceNavigation;
+  registerNode: (id: string, node: View | null) => void;
+}) {
+  const pinNodesRef = useRef<Map<string, View | null>>(new Map());
+  const tree = useMemo(() => buildPartTree(descendantIds, outline), [descendantIds, outline]);
+  return (
+    <View>
+      <FamilyPart
+        member={member}
+        number={undefined}
+        level={1}
+        allMemberIds={allMemberIds}
+        defaultPreviewWidths={defaultPreviewWidths}
+        apiLabel={apiLabel}
+        resolvesAddress={resolvesAddress}
+        navigation={navigation}
+        registerNode={registerNode}
+        afterNameRow={member.partOf ? <PartOfLine partOf={member.partOf} resolvesAddress={resolvesAddress} navigation={navigation} /> : undefined}
+      />
+      {member.anatomy && <AnatomyBox anatomy={member.anatomy} byId={byId} outline={outline} resolvesAddress={resolvesAddress} navigation={navigation} />}
+      {tree.length > 0 && (
+        <View style={styles.subparts}>
+          {tree.map((node) => (
+            <PartTreeBranch
+              key={node.id}
+              node={node}
+              byId={byId}
+              outline={outline}
+              allMemberIds={allMemberIds}
+              defaultPreviewWidths={defaultPreviewWidths}
+              apiLabel={apiLabel}
+              resolvesAddress={resolvesAddress}
+              navigation={navigation}
+              registerNode={registerNode}
+              pinNodesRef={pinNodesRef}
+            />
+          ))}
+        </View>
+      )}
+    </View>
+  );
+}
+
+/**
+ * A group page (#63 A9/R2, layout B): the same page head a family page renders, a jump row (one
+ * chip per top-level member), then one section per top-level member in authored order — no Compare
+ * block, no page-level whole. Every visual piece is reused from `FamilyPage.tsx`; this file only
+ * decides which members are top-level and how their own parts nest under them.
+ */
+export function GroupPage<TId extends string>({
+  def,
+  groupLabel,
+  breadcrumbRoot,
+  banner,
+  pager,
+  headingRef,
+  defaultPreviewWidths,
+  /** Spec §5.3 "Member address", same meaning as `FamilyPage`'s own prop: the member to scroll to
+   *  and focus once this page has rendered. */
+  focusMemberId,
+  focusNonce,
+  knownAddressIds,
+  navigation,
+}: {
+  def: SectionDef<TId>;
+  groupLabel?: string;
+  breadcrumbRoot?: string;
+  banner?: React.ReactNode;
+  pager?: SectionPager<TId>;
+  headingRef?: React.Ref<View>;
+  defaultPreviewWidths?: PreviewWidths;
+  focusMemberId?: string;
+  focusNonce?: number;
+  knownAddressIds?: ReadonlySet<string>;
+  navigation?: ReferenceNavigation<TId>;
+}) {
+  const family = def.family!;
+  const apiLabel = family.apiLabel ?? 'API';
+  const byId = useMemo(() => new Map(family.members.map((member) => [member.id, member])), [family.members]);
+  const allMemberIds = useMemo(() => family.members.map((member) => member.id), [family.members]);
+  const resolvesAddress = useMemo(() => {
+    const ids = new Set<string>([...(knownAddressIds ?? []), ...allMemberIds]);
+    return (name: string) => ids.has(name);
+  }, [knownAddressIds, allMemberIds]);
+
+  // #63 A3: a top-level member has no parent, or a parent that isn't one of this page's own
+  // members (the cross-page case `validateGroup` already accepts) — authored (array) order, the
+  // same "no sections to scan" order every other group derivation already uses.
+  const topLevel = useMemo(() => family.members.filter((member) => member.parent === undefined || !byId.has(member.parent)), [family.members, byId]);
+
+  const childrenOf = useMemo(() => {
+    const map = new Map<string, string[]>();
+    for (const member of family.members) {
+      if (member.parent !== undefined && byId.has(member.parent)) map.set(member.parent, [...(map.get(member.parent) ?? []), member.id]);
+    }
+    return map;
+  }, [family.members, byId]);
+
+  // Every one of a top-level member's own descendants, flattened (not only its direct children) —
+  // both the jump row's own "+k parts" count and `GroupTopLevelMember`'s own `buildPartTree` input
+  // need the full subtree.
+  const descendantsByTopLevel = useMemo(() => {
+    const descendantsOf = (id: string): string[] => {
+      const kids = childrenOf.get(id) ?? [];
+      return [...kids, ...kids.flatMap(descendantsOf)];
+    };
+    return new Map(topLevel.map((member) => [member.id, descendantsOf(member.id)]));
+  }, [topLevel, childrenOf]);
+
+  // A9/R2 item 2: one jump chip per top-level member — its qualifier is "Part N of <Family>" for
+  // an external part, "+k parts" for an embedded family with parts on this page, otherwise none.
+  const jumpItems: JumpItem[] = useMemo(
+    () =>
+      topLevel.map((member) => {
+        const link = memberLink(navigation, resolvesAddress, member.id);
+        const partOf = (member as GroupMember).partOf;
+        const descendantCount = descendantsByTopLevel.get(member.id)?.length ?? 0;
+        const qualifier = partOf
+          ? `Part ${partOf.number} of ${partOf.title}`
+          : descendantCount > 0
+            ? `+${descendantCount} part${descendantCount === 1 ? '' : 's'}`
+            : undefined;
+        return { id: member.id, title: member.id, qualifier, href: link?.href, onPress: link?.onPress };
+      }),
+    [topLevel, navigation, resolvesAddress, descendantsByTopLevel],
+  );
+
+  const nodesRef = useRef<Map<string, View | null>>(new Map());
+  const registerNode = (id: string, node: View | null) => {
+    if (node) nodesRef.current.set(id, node);
+    else nodesRef.current.delete(id);
+  };
+
+  // No folded (`list`-kind) rows exist on a group page (layout B: every top-level member and its
+  // own parts render as blocks) — unlike `FamilyPage`'s own two-phase jump, a member address here
+  // is always already laid out, so one scroll/focus pass per activation is enough.
+  useEffect(() => {
+    if (!focusMemberId) return;
+    const node = nodesRef.current.get(focusMemberId);
+    if (node) scrollAndFocusMember(node);
+  }, [focusMemberId, focusNonce]);
+
+  return (
+    <MemberPanelHost>
+    <View>
+      <FamilyPageHead kind="group" def={def} groupLabel={groupLabel} breadcrumbRoot={breadcrumbRoot} banner={banner} pager={pager} headingRef={headingRef} notShown={family.notShown} />
+
+      {jumpItems.length > 0 && <JumpRow items={jumpItems} />}
+
+      <View style={styles.members}>
+        {topLevel.map((member) => (
+          <GroupTopLevelMember
+            key={member.id}
+            member={member as GroupMember}
+            byId={byId}
+            outline={family.outline}
+            descendantIds={descendantsByTopLevel.get(member.id) ?? []}
+            allMemberIds={allMemberIds}
+            defaultPreviewWidths={defaultPreviewWidths}
+            apiLabel={apiLabel}
+            resolvesAddress={resolvesAddress}
+            navigation={navigation}
+            registerNode={registerNode}
+          />
+        ))}
+      </View>
+    </View>
+    </MemberPanelHost>
+  );
+}
+
+const MEMBER_GAP = 64;
+const PIN_GUTTER = 52;
+
+const styles = StyleSheet.create({
+  // Same rhythm as `FamilyPage`'s own "Parts"/"Related" group body (`labeledGroupBody`) — one
+  // top-level member's section to the next.
+  members: { marginTop: CATALOG_SPACE.xl, gap: MEMBER_GAP },
+  // Same nesting gutter `FamilyPage`'s own `subparts` style uses for a Part's own children.
+  subparts: { marginTop: MEMBER_GAP, marginLeft: PIN_GUTTER, gap: MEMBER_GAP },
+});

package/native/catalog/JumpRow.tsx

@@ -0,0 +1,81 @@
+import React, { useState } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TEXT } from './tokens';
+
+/** #64 B2 / #63 R1: one "On this page" jump chip, shared by a `tokenDefinition` page's category
+ *  row and a group page's top-level-member row. `qualifier` is the small muted text after the
+ *  title (a token page's own entry count, or a group page's "Part N of <Family>"/"+k parts").
+ *  Exactly one of `href` (a real, keyboard-reachable anchor to the target's address — `role="link"`)
+ *  or `onPress` (an in-page scroll, `role="button"`) is the common case; both may be set together
+ *  (a real link that also runs its own handler, the same convention every other canonical link in
+ *  this codebase already uses — see `catalogReferences.ts`'s `referenceLinkProps`). */
+export interface JumpItem {
+  /** React key — the chip's own target id (a token section id, or a group member id). */
+  id: string;
+  title: string;
+  qualifier?: string;
+  /** Overrides the default accessible name (`title`, or `"<title>, <qualifier>"` when a qualifier
+   *  is set) — a token page's own chip keeps its established "N value(s)" wording this way. */
+  accessibilityLabel?: string;
+  href?: string;
+  onPress?: (event?: { preventDefault?: () => void; metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean; button?: number }) => void;
+}
+
+export function JumpChip({ title, qualifier, accessibilityLabel, href, onPress }: Omit<JumpItem, 'id'>) {
+  const [hovered, setHovered] = useState(false);
+  const [focused, setFocused] = useState(false);
+  return (
+    <Pressable
+      onPress={onPress}
+      onHoverIn={() => setHovered(true)}
+      onHoverOut={() => setHovered(false)}
+      onFocus={() => setFocused(true)}
+      onBlur={() => setFocused(false)}
+      accessibilityRole={href ? 'link' : 'button'}
+      accessibilityLabel={accessibilityLabel ?? (qualifier ? `${title}, ${qualifier}` : undefined)}
+      // `href` renders a real `<a href="#Id">` on web (react-native-web leaves keyboard activation
+      // of role="link" to the browser's own anchor handling) — the same convention
+      // `catalogReferences.ts`'s link producers already establish.
+      {...(href ? ({ href } as Record<string, unknown>) : null)}
+      style={({ pressed }) => [styles.jumpChip, (pressed || hovered) && styles.jumpChipHover, focused && styles.focusRing]}
+    >
+      <Text style={styles.jumpChipTitle}>{title}</Text>
+      {qualifier ? <Text style={styles.jumpChipCount}>{qualifier}</Text> : null}
+    </Pressable>
+  );
+}
+
+/** #64 B2: a token page's category jump row, and (#63 R1) a group page's top-level-member jump
+ *  row — one chip per item, in authored order. */
+export function JumpRow({ items }: { items: readonly JumpItem[] }) {
+  return (
+    <View style={styles.jumpRow} accessibilityRole="list">
+      {/* `role="list"` must own `listitem` children, so each chip sits in its own item. */}
+      {items.map((item) => (
+        <View key={item.id} role="listitem">
+          <JumpChip title={item.title} qualifier={item.qualifier} accessibilityLabel={item.accessibilityLabel} href={item.href} onPress={item.onPress} />
+        </View>
+      ))}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // #64 B2: the jump row's own chip/pill look — the catalog's existing chip/pill visual
+  // (`CATALOG_COLOR.chip`, the same muted rounded pill `UpdatePanel.tsx`'s own status pills use),
+  // never a new visual.
+  jumpRow: { flexDirection: 'row', flexWrap: 'wrap', gap: CATALOG_SPACE.sm, marginBottom: CATALOG_LAYOUT.blockLabelGap },
+  jumpChip: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: CATALOG_SPACE.xs,
+    paddingHorizontal: CATALOG_SPACE.sm,
+    paddingVertical: 4,
+    borderRadius: CATALOG_RADIUS.control,
+    backgroundColor: CATALOG_COLOR.chip,
+  },
+  jumpChipHover: { backgroundColor: CATALOG_COLOR.surfacePressed },
+  jumpChipTitle: { ...CATALOG_TEXT.captionStrong, color: CATALOG_COLOR.text },
+  jumpChipCount: { ...CATALOG_TEXT.micro, color: CATALOG_COLOR.textMuted },
+  focusRing: { outlineWidth: CATALOG_LAYOUT.focusRingWidth, outlineStyle: 'solid', outlineColor: CATALOG_COLOR.focusRing },
+});

package/native/catalog/ReferenceDetails.tsx

@@ -3,7 +3,22 @@ import { View, Text, StyleSheet, type LayoutChangeEvent, type TextStyle } from '
 import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TEXT } from './tokens';
 import { PropsTable } from './PropsTable';
 import { propsColumns, referenceColumns } from './comparison';
-import type { ComposedOfEntry, SectionDef } from './types';
+import { hashForId } from './catalogNavigation';
+import { referenceLinkProps, type ReferenceNavigation } from './catalogReferences';
+import { alsoUsedBySegments } from './familyModel';
+import type { AlsoUsedByEntry, ComposedOfEntry, SectionDef } from './types';
+
+/** `referenceLinkProps` returns the resolved target, not a ready-made `href` (see its own doc
+ *  comment in `catalogReferences.ts`) — this builds the real link props every `Text role="link"`
+ *  below actually spreads, the one place in this file that turns a target into `hashForId(memberId
+ *  ?? pageId)`. */
+function linkProps<TId extends string>(
+  navigation: ReferenceNavigation<TId> | undefined,
+  name: string,
+): { href: string; onPress: (event?: { preventDefault?: () => void }) => void } | undefined {
+  const activation = referenceLinkProps(navigation, name);
+  return activation ? { href: hashForId(activation.memberId ?? activation.pageId), onPress: activation.onPress } : undefined;
+}
 
 // react-native-web reads `aria-level`; React Native's prop types do not declare it.
 const HEADING_LEVEL_2 = { 'aria-level': 2 } as Record<string, unknown>;
@@ -46,18 +61,57 @@ function PropsBox<TId extends string>({ def }: { def: SectionDef<TId> }) {
 // `built-in` is composition's assumed default relationship, so spelling it out reads redundantly
 // (e.g. "TrainArrivalRemainingTime · built-in"); `slot`/`related` still need their own suffix to
 // stay distinguishable from a plain built-in entry.
-function compositionLabel(entry: ComposedOfEntry): string {
-  return entry.relationship === 'built-in' ? entry.component : `${entry.component} · ${entry.relationship}`;
+function compositionSuffix(entry: ComposedOfEntry): string {
+  return entry.relationship === 'built-in' ? '' : ` · ${entry.relationship}`;
+}
+
+/** One Composition row: the name links to its real canonical address when `navigation` resolves it
+ *  (plan #60: "Ordinary Composition references become real links when resolvable … unresolved
+ *  names remain honest plain text") — a relationship suffix, when any, stays outside the link, the
+ *  same way `UsesLine` in `FamilyPage.tsx` keeps its own `(role)` text unlinked. `navigation`
+ *  omitted keeps the prior plain-text rendering untouched (a standalone-mounted `ReferenceDetails`,
+ *  this framework's own catalog demo included). */
+function CompositionFact<TId extends string>({
+  entry,
+  navigation,
+  last = false,
+}: {
+  entry: ComposedOfEntry;
+  navigation?: ReferenceNavigation<TId>;
+  last?: boolean;
+}) {
+  const link = linkProps(navigation, entry.component);
+  return (
+    <View style={[styles.fact, last && styles.factLast]}>
+      <Text style={styles.factLabel}>
+        {link ? (
+          <Text role="link" style={styles.factLabelLink} {...link}>{entry.component}</Text>
+        ) : (
+          entry.component
+        )}
+        {compositionSuffix(entry)}
+      </Text>
+      <Text style={styles.factValue}>{entry.role}</Text>
+    </View>
+  );
 }
 
-function CompositionFacts({ composedOf, lastIsFlush = false }: { composedOf: ComposedOfEntry[]; lastIsFlush?: boolean }) {
+function CompositionFacts<TId extends string>({
+  composedOf,
+  lastIsFlush = false,
+  navigation,
+}: {
+  composedOf: ComposedOfEntry[];
+  lastIsFlush?: boolean;
+  navigation?: ReferenceNavigation<TId>;
+}) {
   return (
     <>
       {composedOf.map((entry, i) => (
-        <Fact
+        <CompositionFact
           key={`${entry.component}-${entry.relationship}-${i}`}
-          label={compositionLabel(entry)}
-          value={entry.role}
+          entry={entry}
+          navigation={navigation}
           last={lastIsFlush && i === composedOf.length - 1}
         />
       ))}
@@ -65,6 +119,56 @@ function CompositionFacts({ composedOf, lastIsFlush = false }: { composedOf: Com
   );
 }
 
+/** The page's own `notes` as one Quick reference entry — one bullet per note, the same `• ` style
+ *  a family member's notes use in its side panel. */
+function NotesFact({ notes, last = false }: { notes: readonly string[]; last?: boolean }) {
+  return (
+    <View style={[styles.fact, last && styles.factLast]}>
+      <Text style={styles.factLabel}>Notes</Text>
+      {notes.map((note, i) => (
+        <Text key={i} style={styles.factValue}>
+          {'• '}
+          {note}
+        </Text>
+      ))}
+    </View>
+  );
+}
+
+/** The derived "Also used by …" row (`SectionDef.alsoUsedBy`, plan #60's ordinary-page inverse of
+ *  `FamilyDef.members[].alsoUsedBy`): the exact same sentence/segment shape
+ *  `alsoUsedBySegments`/`WholeBelowLine` already render on a family page, so an ordinary page's own
+ *  cross-use reads identically — a resolvable user links, an unresolvable one stays honest plain
+ *  text. Renders nothing for an empty list (the overwhelming majority of pages): no row, no label,
+ *  no gap — the same "nothing renders when nothing else uses it" rule the README already documents
+ *  for a family member. */
+function AlsoUsedByFact<TId extends string>({
+  entries,
+  navigation,
+  last = false,
+}: {
+  entries: readonly AlsoUsedByEntry[];
+  navigation?: ReferenceNavigation<TId>;
+  last?: boolean;
+}) {
+  const segments = alsoUsedBySegments(entries);
+  if (segments.length === 0) return null;
+  return (
+    <View style={[styles.fact, last && styles.factLast]}>
+      <Text style={styles.factValue}>
+        {segments.map((segment, i) => {
+          const link = segment.component ? linkProps(navigation, segment.component) : undefined;
+          return link ? (
+            <Text key={i} role="link" style={styles.factLabelLink} {...link}>{segment.text}</Text>
+          ) : (
+            <Text key={i}>{segment.text}</Text>
+          );
+        })}
+      </Text>
+    </View>
+  );
+}
+
 /**
  * Always-visible reference below a page's specimens: a card with Guidance, Quick reference
  * (source path, accessibility), and — only when the page has confirmed composition to disclose —
@@ -86,26 +190,41 @@ function CompositionFacts({ composedOf, lastIsFlush = false }: { composedOf: Com
  * outer card previously fed `referenceColumns` an outer width up to ~42px wider than what the three
  * columns' content actually has, which can report a column count the inner content doesn't fit.
  */
-export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<TId> }) {
+export function ReferenceDetails<TId extends string>({
+  def,
+  navigation,
+}: {
+  def: SectionDef<TId>;
+  /** Task 2B2: `CatalogShell`'s own shared reference navigation (see `catalogReferences.ts`'s
+   *  `ReferenceNavigation`/`referenceLinkProps`) — turns a resolvable Composition name into a real
+   *  canonical link. Omitted (a standalone-mounted `ReferenceDetails`, this framework's own catalog
+   *  demo included) keeps every name as it always rendered: plain text, no link. */
+  navigation?: ReferenceNavigation<TId>;
+}) {
   const hide = def.hide ?? {};
   const [width, setWidth] = useState(0);
   const onLayout = (event: LayoutChangeEvent) => {
     const next = Math.round(event.nativeEvent.layout.width);
     if (next > 0 && next !== width) setWidth(next);
   };
+  const hasAlsoUsedBy = Boolean(def.alsoUsedBy && def.alsoUsedBy.length > 0);
+  const hasNotes = Boolean(def.notes && def.notes.length > 0);
   if (def.tokenGallery) {
     // Full-width pages with no component API (token galleries, and whole screens such as a
     // starter kit's Patterns) still disclose what they're built from when they say so.
+    const hasComposition = Boolean(def.composedOf && def.composedOf.length > 0);
     return (
       <View style={styles.card}>
         <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
-        {def.path && <Fact label="Source" value={def.path} mono last={!(def.composedOf && def.composedOf.length > 0)} />}
-        {def.composedOf && def.composedOf.length > 0 && (
+        {def.path && <Fact label="Source" value={def.path} mono last={!hasNotes && !hasComposition && !hasAlsoUsedBy} />}
+        {hasNotes && <NotesFact notes={def.notes!} last={!hasComposition && !hasAlsoUsedBy} />}
+        {hasComposition && def.composedOf && (
           <>
             <Text style={styles.subheading}>Composition</Text>
-            <CompositionFacts composedOf={def.composedOf} lastIsFlush />
+            <CompositionFacts composedOf={def.composedOf} lastIsFlush={!hasAlsoUsedBy} navigation={navigation} />
           </>
         )}
+        {hasAlsoUsedBy && <AlsoUsedByFact entries={def.alsoUsedBy!} navigation={navigation} last />}
       </View>
     );
   }
@@ -114,6 +233,10 @@ export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<
   const stacked = columns === 1;
   const compositionIsOwnColumn = columns === 3 && hasComposition;
   const columnStyle = stacked ? styles.columnStacked : styles.column;
+  // "Also used by" always sits in Quick reference, after Composition when nested there too — it
+  // never gets its own column (plan #60: it's the always-visible inverse of an existing fact, not
+  // a new confirmed-data column like Composition).
+  const compositionNestedHere = !compositionIsOwnColumn && hasComposition;
 
   return (
     <View style={styles.stack}>
@@ -125,25 +248,27 @@ export function ReferenceDetails<TId extends string>({ def }: { def: SectionDef<
           </View>
           <View style={columnStyle}>
             <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Quick reference</Text>
-            {def.path && <Fact label="Source" value={def.path} mono last={hide.accessibility && !(!compositionIsOwnColumn && hasComposition)} />}
+            {def.path && <Fact label="Source" value={def.path} mono last={hide.accessibility && !hasNotes && !compositionNestedHere && !hasAlsoUsedBy} />}
             {!hide.accessibility && (
               <Fact
                 label="Accessibility"
                 value={def.a11y ?? 'No accessibility notes documented.'}
-                last={!(!compositionIsOwnColumn && hasComposition)}
+                last={!hasNotes && !compositionNestedHere && !hasAlsoUsedBy}
               />
             )}
-            {!compositionIsOwnColumn && hasComposition && def.composedOf && (
+            {hasNotes && <NotesFact notes={def.notes!} last={!compositionNestedHere && !hasAlsoUsedBy} />}
+            {compositionNestedHere && def.composedOf && (
               <>
                 <Text style={styles.subheading}>Composition</Text>
-                <CompositionFacts composedOf={def.composedOf} lastIsFlush />
+                <CompositionFacts composedOf={def.composedOf} lastIsFlush={!hasAlsoUsedBy} navigation={navigation} />
               </>
             )}
+            {hasAlsoUsedBy && <AlsoUsedByFact entries={def.alsoUsedBy!} navigation={navigation} last />}
           </View>
           {compositionIsOwnColumn && def.composedOf && (
             <View style={columnStyle}>
               <Text role="heading" {...HEADING_LEVEL_2} style={styles.heading}>Composition</Text>
-              <CompositionFacts composedOf={def.composedOf} lastIsFlush />
+              <CompositionFacts composedOf={def.composedOf} lastIsFlush navigation={navigation} />
             </View>
           )}
         </View>
@@ -187,6 +312,9 @@ const styles = StyleSheet.create({
   },
   factLast: { paddingBottom: 0, borderBottomWidth: 0 },
   factLabel: { flexShrink: 1, minWidth: 0, ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.text },
+  // Same accent treatment every other in-app reference link already uses (`FamilyPage.tsx`'s own
+  // `relatedLink`) — a linked Composition/"also used by" name reads the same way across both pages.
+  factLabelLink: { ...CATALOG_TEXT.bodyStrong, color: CATALOG_COLOR.accent },
   factValue: { minWidth: 0, ...CATALOG_TEXT.body, textAlign: 'left', color: CATALOG_COLOR.textMuted },
   // `wordBreak` isn't in the installed `TextStyle` type (RN's own, not RNW's — RNW's own
   // `Text/types.js` declares it; a browser applies any valid CSS property name it recognizes