@krapwoo/ds-viewer 0.13.1 → 0.14.0

package/README.md

@@ -537,6 +537,20 @@ export default defineCatalogPage({
   resolves to a real catalog address (a page, another member, or an alias — in this family or any
   other), otherwise it shows in code; an unknown name logs a `[Catalog]` warning the same way the
   page-level field's does.
+- **"Also used by …"** is derived, never authored — there is no field for it anywhere. It's the
+  inverse of the "Uses …" line above: if some other page or member's own `composedOf` names this
+  one with `relationship: 'built-in'`, that's already a declaration that the other one uses it;
+  `buildCatalogSections` inverts every such declaration across the whole catalog and shows the
+  result as a short line below the member's specimens (joining the same line as its source path),
+  so the same relationship never has to be authored a second time from this end. Only `'built-in'`
+  counts — `'slot'` and `'related'` never produce a line. A user that is this member's own parent,
+  the page's own whole, the member itself, or any other member of the same family page is excluded:
+  that edge is the family tree already, not a second user. One user shows as `Also used by X
+  (role)` (role omitted when empty); two or three as `Also used by X, Y and Z`, with no roles —
+  they bloat the line; more than three as `Also used by X, Y and Z +N more`, with `+N more` as
+  plain text. A user that resolves to a real catalog address links the same way a
+  `related`/`composedOf` name does; otherwise it shows as plain text. Nothing renders when nothing
+  else uses the member — the overwhelming majority of them.
 - **`notShown`** (page-level) is a short "Not shown in the browser: …" line under the page head,
   for behavior a web catalog can't demonstrate (a timer, a native gesture). A member's own
   `notShown` works the same way, under its specimens. Like `aliases`, the page-level field only

package/dist/native/catalog/pageApi.js

@@ -309,6 +309,48 @@ pages, components, groupOrder) {
         ...pages.flatMap((page) => (page.members ?? []).flatMap((member) => member.aliases ?? [])),
         ...pages.flatMap((page) => page.aliases ?? []),
     ]);
+    // A member only ever looks itself up (below) by its own canonical `id`, but `knownComposedOfNames`
+    // (N8, above) deliberately lets a `composedOf` entry's own `component` name a member's *alias*, or
+    // the member's `component` field instead of its `id` — both resolve as working links through
+    // `FamilyPage`'s own `resolvesAddress`. Without resolving through the same map here, an
+    // alias-named or component-named entry would link fine going forward but derive nothing going
+    // back: a missing "Also used by" line looks identical to "nothing uses this".
+    const canonicalMemberIdByAlias = new Map();
+    for (const page of pages) {
+        for (const member of page.members ?? []) {
+            for (const alias of member.aliases ?? [])
+                canonicalMemberIdByAlias.set(alias, member.id);
+            if (member.component && member.component !== member.id)
+                canonicalMemberIdByAlias.set(member.component, member.id);
+        }
+    }
+    const canonicalUsedByTarget = (name) => canonicalMemberIdByAlias.get(name) ?? name;
+    // "Also used by" (derived, never authored): the inverse of every `composedOf` entry in the
+    // catalog whose `relationship` is `'built-in'` — the forward direction renders as "Uses X"
+    // (`UsesLine`); this is that same relationship read from the other end, keyed by the entry's own
+    // `component` (the used thing) — gathered once, up front, so a family member just looks up its
+    // own id below. A page's own `composedOf` attributes to that page's id (its address, e.g. a
+    // family's whole); a family member's own `composedOf` attributes to that member's own id.
+    const usedByTarget = new Map();
+    const addUsedBy = (target, component, role) => {
+        const list = usedByTarget.get(target);
+        if (list)
+            list.push({ component, role });
+        else
+            usedByTarget.set(target, [{ component, role }]);
+    };
+    for (const page of pages) {
+        for (const entry of page.composedOf ?? []) {
+            if (entry.relationship === 'built-in')
+                addUsedBy(canonicalUsedByTarget(entry.component), page.id, entry.role);
+        }
+        for (const member of page.members ?? []) {
+            for (const entry of member.composedOf ?? []) {
+                if (entry.relationship === 'built-in')
+                    addUsedBy(canonicalUsedByTarget(entry.component), member.id, entry.role);
+            }
+        }
+    }
     // Every id/alias a family page's own `members` and `aliases` use, keyed by page id — gathered up
     // front so `validateFamily` (above) can check catalog-wide uniqueness against every *other*
     // page's ids.
@@ -375,6 +417,10 @@ pages, components, groupOrder) {
                 for (const issue of issues)
                     console.error(`[Catalog] ${issue}`);
             }
+            // "Also used by": every id this page's own members (the whole included) use is excluded
+            // from its own members' derived users — a sibling (or the whole) composing a part is still
+            // the same family tree, already expressed by `parent`/the page itself, not a second user.
+            const pageMemberIds = new Set(page.members.map((m) => m.id));
             family = {
                 whole: page.whole,
                 sections: page.sections,
@@ -386,10 +432,26 @@ pages, components, groupOrder) {
                 relatedPages: page.relatedPages,
                 members: page.members.map((member) => {
                     const memberComponent = member.component ? componentByName.get(member.component) : undefined;
+                    // Dedupe by `component`, keeping the first role: page-level and whole-member `composedOf`
+                    // attribute to the same string for a family's whole (`validateFamily` forces
+                    // `whole === page.id`), and `validateComposedOf` has no duplicate check of its own, so the
+                    // same user declared twice would otherwise render "Also used by P and P".
+                    const dedupedUsers = new Map();
+                    for (const entry of usedByTarget.get(member.id) ?? []) {
+                        if (pageMemberIds.has(entry.component))
+                            continue;
+                        if (!dedupedUsers.has(entry.component))
+                            dedupedUsers.set(entry.component, entry);
+                    }
+                    const alsoUsedBy = [...dedupedUsers.values()].map((entry) => ({
+                        component: entry.component,
+                        role: entry.role || undefined,
+                    }));
                     return {
                         ...member,
                         props: memberComponent ? mergePropNotes(memberComponent, undefined) : undefined,
                         path: memberComponent?.file ?? member.source,
+                        alsoUsedBy,
                     };
                 }),
             };

package/native/catalog/FamilyPage.tsx

@@ -11,6 +11,7 @@ import { hashForId } from './catalogNavigation';
 // component with no test of its own that imports it directly under Node, so it only ever goes
 // through the bundler.
 import {
+  alsoUsedBySegments,
   anatomyColumns,
   anatomyPinFor,
   ariaLevelFor,
@@ -26,7 +27,7 @@ import {
   type PartTreeEntry,
   type RelatedSegment,
 } from './familyModel';
-import type { CatalogAnatomy, CatalogAnatomyGroup, CatalogMember, CatalogMemberSection, ComposedOfEntry, FamilyDef, PreviewWidths, PropDef, RelatedPage, SectionDef } from './types';
+import type { AlsoUsedByEntry, CatalogAnatomy, CatalogAnatomyGroup, CatalogMember, CatalogMemberSection, ComposedOfEntry, FamilyDef, PreviewWidths, PropDef, RelatedPage, SectionDef } from './types';
 
 /** `SectionDef`'s parts `presentationBlocks`/`Blocks` actually read, built from one family member
  *  so its own specimens render through the exact same renderers (`VariantGroup`, `ComparisonGrid`,
@@ -125,21 +126,28 @@ function MemberNameRow({
   );
 }
 
-/** `[related ·] [relationship ·] source path:line` (spec §5.2 "Below the specimens"). A member
- *  name inside `related` is a link to that member's address — a real `href`, like every other
+/** `[related ·] [relationship ·] source [· Also used by …]` (spec §5.2 "Below the specimens",
+ *  derived "also used by" slice). A member name inside `related`, and a resolvable component in
+ *  the derived "Also used by" segment, both link to that address — a real `href`, like every other
  *  in-app link, so clicking it goes through the same `hashchange` routing as typing the address or
- *  using search (`CatalogShell`). */
+ *  using search (`CatalogShell`). An unresolvable user (a declared user with no catalog page of its
+ *  own) renders as plain text instead, the same way `UsesLine` treats an unresolvable name. */
 function BelowSpecimensLine({
   related,
   showRelationship,
   relationship,
   source,
+  alsoUsedBy,
+  resolvesAddress,
 }: {
   related?: RelatedSegment[];
   showRelationship: boolean;
   relationship: string;
   source: string;
+  alsoUsedBy: AlsoUsedByEntry[];
+  resolvesAddress: (name: string) => boolean;
 }) {
+  const usedBy = alsoUsedBySegments(alsoUsedBy);
   return (
     <Text style={styles.belowLine}>
       {related &&
@@ -155,13 +163,37 @@ function BelowSpecimensLine({
       {related && ' · '}
       {showRelationship && `${relationship} · `}
       {source}
+      {usedBy.length > 0 && ' · '}
+      {usedBy.map((segment, i) =>
+        segment.component && resolvesAddress(segment.component) ? (
+          <Text key={i} role="link" style={styles.relatedLink} {...({ href: hashForId(segment.component) } as Record<string, unknown>)}>
+            {segment.text}
+          </Text>
+        ) : (
+          <Text key={i}>{segment.text}</Text>
+        ),
+      )}
     </Text>
   );
 }
 
-/** Slice D1 item 6: the whole's own one-line summary — `<name> · <fidelity badge> · <source>` — in
- *  place of the below-specimens line (the whole has no `relationship`/`related` to show). */
-function WholeBelowLine({ name, fidelity, source }: { name: string; fidelity: CatalogMember['fidelity']; source: string }) {
+/** Slice D1 item 6: the whole's own one-line summary — `<name> · <fidelity badge> · <source>
+ *  [· Also used by …]` — in place of the below-specimens line (the whole has no
+ *  `relationship`/`related` to show, but it is still a member, so it still derives users). */
+function WholeBelowLine({
+  name,
+  fidelity,
+  source,
+  alsoUsedBy,
+  resolvesAddress,
+}: {
+  name: string;
+  fidelity: CatalogMember['fidelity'];
+  source: string;
+  alsoUsedBy: AlsoUsedByEntry[];
+  resolvesAddress: (name: string) => boolean;
+}) {
+  const usedBy = alsoUsedBySegments(alsoUsedBy);
   return (
     <View style={styles.wholeBelowRow}>
       <Text style={styles.wholeName}>{name}</Text>
@@ -169,6 +201,18 @@ function WholeBelowLine({ name, fidelity, source }: { name: string; fidelity: Ca
       <FidelityBadge fidelity={fidelity} />
       <Text style={styles.belowLine}> · </Text>
       <Text style={styles.belowLine}>{source}</Text>
+      {usedBy.length > 0 && <Text style={styles.belowLine}> · </Text>}
+      {usedBy.map((segment, i) =>
+        segment.component && resolvesAddress(segment.component) ? (
+          <Text key={i} role="link" style={styles.relatedLink} {...({ href: hashForId(segment.component) } as Record<string, unknown>)}>
+            {segment.text}
+          </Text>
+        ) : (
+          <Text key={i} style={styles.belowLine}>
+            {segment.text}
+          </Text>
+        ),
+      )}
     </View>
   );
 }
@@ -294,7 +338,7 @@ function MemberDisclosureToggle({
   );
 }
 
-type FamilyMember = CatalogMember & { props?: PropDef[]; path: string };
+type FamilyMember = CatalogMember & { props?: PropDef[]; path: string; alsoUsedBy?: AlsoUsedByEntry[] };
 
 interface MemberRenderProps {
   member: FamilyMember;
@@ -377,6 +421,8 @@ function FamilyPart({ member, number, level, allMemberIds, defaultPreviewWidths,
           showRelationship={false}
           relationship={member.relationship}
           source={member.source}
+          alsoUsedBy={member.alsoUsedBy ?? []}
+          resolvesAddress={resolvesAddress}
         />
         <View style={styles.disclosureSpacer}>
           <MemberDisclosureToggle member={member} apiLabel={apiLabel} resolvesAddress={resolvesAddress} />
@@ -421,7 +467,14 @@ function FoldedRow({ member, number, allMemberIds, resolvesAddress, open, onTogg
           web must never bubble its own click into this row's own press handler and close it. */}
       {open && (
         <View style={styles.foldedRowBody}>
-          <BelowSpecimensLine related={related} showRelationship={false} relationship={member.relationship} source={member.source} />
+          <BelowSpecimensLine
+            related={related}
+            showRelationship={false}
+            relationship={member.relationship}
+            source={member.source}
+            alsoUsedBy={member.alsoUsedBy ?? []}
+            resolvesAddress={resolvesAddress}
+          />
           {parts.length > 0 && (
             <DisclosureBody member={member} parts={parts} resolvedProps={member.props} resolvesAddress={resolvesAddress} />
           )}
@@ -1055,7 +1108,13 @@ export function FamilyPage<TId extends string>({
                   </View>
                 )}
                 {wholeMember.notShown && <Text style={styles.belowLine}>{wholeMember.notShown}</Text>}
-                <WholeBelowLine name={wholeMember.id} fidelity={wholeMember.fidelity} source={wholeMember.source} />
+                <WholeBelowLine
+                  name={wholeMember.id}
+                  fidelity={wholeMember.fidelity}
+                  source={wholeMember.source}
+                  alsoUsedBy={wholeMember.alsoUsedBy ?? []}
+                  resolvesAddress={resolvesAddress}
+                />
                 <View style={styles.disclosureSpacer}>
                   <MemberDisclosureToggle member={wholeMember} apiLabel={apiLabel} resolvesAddress={resolvesAddress} />
                 </View>

package/native/catalog/familyModel.ts

@@ -4,7 +4,7 @@
  * building, disclosure content, and link/pin lookups. Outline numbering (`numberFor`) and family
  * validation (`validateFamily`) live in `pageApi.ts` instead — see that file's own comments.
  */
-import type { CatalogMember, CatalogMemberSection, PropDef } from './types.ts';
+import type { AlsoUsedByEntry, CatalogMember, CatalogMemberSection, PropDef } from './types.ts';
 
 /** One node of a `blocks` section's own Part tree (Slice D1 item 7 "Tree line"). */
 export interface PartTreeEntry {
@@ -163,6 +163,37 @@ export interface RelatedSegment {
   memberId?: string;
 }
 
+/** One segment of an "Also used by" line: plain text, or another component's own id, rendered as a
+ *  link when it resolves to a real catalog address and plain text otherwise (`FamilyPage`'s own
+ *  `resolvesAddress`, the same test `UsesLine` already uses). */
+export interface UsedBySegment {
+  text: string;
+  component?: string;
+}
+
+/** Builds the "Also used by …" segments (field spec "Rendering") from a member's derived
+ *  `alsoUsedBy` list: `[]` for none (the caller renders nothing), one user with its own role in
+ *  parentheses when non-empty, two or three joined with commas and "and" (no roles — they bloat the
+ *  line), or the first three plus a plain-text "+N more" beyond that. */
+export function alsoUsedBySegments(entries: readonly AlsoUsedByEntry[]): UsedBySegment[] {
+  if (entries.length === 0) return [];
+  const segments: UsedBySegment[] = [{ text: 'Also used by ' }];
+  if (entries.length === 1) {
+    const [entry] = entries;
+    segments.push({ text: entry.component, component: entry.component });
+    if (entry.role) segments.push({ text: ` (${entry.role})` });
+    return segments;
+  }
+  const shown = entries.slice(0, 3);
+  shown.forEach((entry, i) => {
+    segments.push({ text: entry.component, component: entry.component });
+    if (i < shown.length - 2) segments.push({ text: ', ' });
+    else if (i === shown.length - 2) segments.push({ text: ' and ' });
+  });
+  if (entries.length > 3) segments.push({ text: ` +${entries.length - 3} more` });
+  return segments;
+}
+
 /** Escapes a string for literal use inside a `RegExp` (the characters the regex engine would
  *  otherwise treat as metacharacters). A Swift declaration name never contains any of these, but
  *  this keeps `linkifyRelated` correct even if one ever did. */

package/native/catalog/index.ts

@@ -48,7 +48,7 @@ export { defineCatalogPage, buildCatalogSections } from './pageApi';
 export type { CatalogPage, CatalogPageInput, GeneratedComponent, GeneratedPropRecord } from './pageApi';
 export type {
   PropDef, SectionDef, NavGroup, SpecimenSize, SpecimenSurfaceKind, ComparisonDef, ComparisonCell, ComparisonAxisItem, GridAxis,
-  PreviewWidths, TokenSection, ComposedOfEntry, CatalogMember, CatalogMemberSection, FamilyDef,
+  PreviewWidths, TokenSection, ComposedOfEntry, AlsoUsedByEntry, CatalogMember, CatalogMemberSection, FamilyDef,
   CatalogAnatomy, CatalogAnatomyGroup, CatalogAnatomyItem, RelatedPage,
 } from './types';
 export { UpdatePanel } from './UpdatePanel';

package/native/catalog/pageApi.ts

@@ -1,5 +1,5 @@
 import type React from 'react';
-import type { CatalogAnatomy, CatalogMember, CatalogMemberSection, ComparisonDef, ComposedOfEntry, NavGroup, PreviewWidths, PropDef, RelatedPage, SectionDef, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot } from './types.ts';
+import type { AlsoUsedByEntry, CatalogAnatomy, CatalogMember, CatalogMemberSection, ComparisonDef, ComposedOfEntry, NavGroup, PreviewWidths, PropDef, RelatedPage, SectionDef, SpecimenSize, SpecimenSurfaceKind, TokenSection, VariantSlot } from './types.ts';
 
 /** `SectionDef` without the derived fields (`id`/`path`/`props` come from detection and
  *  generated props), plus the three fields design §1 "Page shape" adds. */
@@ -447,6 +447,44 @@ export function buildCatalogSections<TId extends string>(
     ...pages.flatMap((page) => page.aliases ?? []),
   ]);
 
+  // A member only ever looks itself up (below) by its own canonical `id`, but `knownComposedOfNames`
+  // (N8, above) deliberately lets a `composedOf` entry's own `component` name a member's *alias*, or
+  // the member's `component` field instead of its `id` — both resolve as working links through
+  // `FamilyPage`'s own `resolvesAddress`. Without resolving through the same map here, an
+  // alias-named or component-named entry would link fine going forward but derive nothing going
+  // back: a missing "Also used by" line looks identical to "nothing uses this".
+  const canonicalMemberIdByAlias = new Map<string, string>();
+  for (const page of pages) {
+    for (const member of page.members ?? []) {
+      for (const alias of member.aliases ?? []) canonicalMemberIdByAlias.set(alias, member.id);
+      if (member.component && member.component !== member.id) canonicalMemberIdByAlias.set(member.component, member.id);
+    }
+  }
+  const canonicalUsedByTarget = (name: string) => canonicalMemberIdByAlias.get(name) ?? name;
+
+  // "Also used by" (derived, never authored): the inverse of every `composedOf` entry in the
+  // catalog whose `relationship` is `'built-in'` — the forward direction renders as "Uses X"
+  // (`UsesLine`); this is that same relationship read from the other end, keyed by the entry's own
+  // `component` (the used thing) — gathered once, up front, so a family member just looks up its
+  // own id below. A page's own `composedOf` attributes to that page's id (its address, e.g. a
+  // family's whole); a family member's own `composedOf` attributes to that member's own id.
+  const usedByTarget = new Map<string, Array<{ component: string; role: string }>>();
+  const addUsedBy = (target: string, component: string, role: string) => {
+    const list = usedByTarget.get(target);
+    if (list) list.push({ component, role });
+    else usedByTarget.set(target, [{ component, role }]);
+  };
+  for (const page of pages) {
+    for (const entry of page.composedOf ?? []) {
+      if (entry.relationship === 'built-in') addUsedBy(canonicalUsedByTarget(entry.component), page.id, entry.role);
+    }
+    for (const member of page.members ?? []) {
+      for (const entry of member.composedOf ?? []) {
+        if (entry.relationship === 'built-in') addUsedBy(canonicalUsedByTarget(entry.component), member.id, entry.role);
+      }
+    }
+  }
+
   // Every id/alias a family page's own `members` and `aliases` use, keyed by page id — gathered up
   // front so `validateFamily` (above) can check catalog-wide uniqueness against every *other*
   // page's ids.
@@ -507,6 +545,10 @@ export function buildCatalogSections<TId extends string>(
       if ((globalThis as { __DEV__?: boolean }).__DEV__) {
         for (const issue of issues) console.error(`[Catalog] ${issue}`);
       }
+      // "Also used by": every id this page's own members (the whole included) use is excluded
+      // from its own members' derived users — a sibling (or the whole) composing a part is still
+      // the same family tree, already expressed by `parent`/the page itself, not a second user.
+      const pageMemberIds = new Set(page.members!.map((m) => m.id));
       family = {
         whole: page.whole!,
         sections: page.sections!,
@@ -518,10 +560,24 @@ export function buildCatalogSections<TId extends string>(
         relatedPages: page.relatedPages,
         members: page.members!.map((member) => {
           const memberComponent = member.component ? componentByName.get(member.component) : undefined;
+          // Dedupe by `component`, keeping the first role: page-level and whole-member `composedOf`
+          // attribute to the same string for a family's whole (`validateFamily` forces
+          // `whole === page.id`), and `validateComposedOf` has no duplicate check of its own, so the
+          // same user declared twice would otherwise render "Also used by P and P".
+          const dedupedUsers = new Map<string, { component: string; role: string }>();
+          for (const entry of usedByTarget.get(member.id) ?? []) {
+            if (pageMemberIds.has(entry.component)) continue;
+            if (!dedupedUsers.has(entry.component)) dedupedUsers.set(entry.component, entry);
+          }
+          const alsoUsedBy: AlsoUsedByEntry[] = [...dedupedUsers.values()].map((entry) => ({
+            component: entry.component,
+            role: entry.role || undefined,
+          }));
           return {
             ...member,
             props: memberComponent ? mergePropNotes(memberComponent, undefined) : undefined,
             path: memberComponent?.file ?? member.source,
+            alsoUsedBy,
           };
         }),
       };

package/native/catalog/types.ts

@@ -107,6 +107,19 @@ export interface ComposedOfEntry {
   relationship: 'built-in' | 'slot' | 'related';
 }
 
+/** Derived (never authored) — the inverse of every other page's or member's own `composedOf`
+ *  entry whose `relationship` is `'built-in'`: if something else's `composedOf` names this member,
+ *  that something is "also used by" it. The forward direction (that other `composedOf`) renders as
+ *  "Uses X" (`UsesLine`); this is the same relationship read from the other end. Computed once, by
+ *  `buildCatalogSections`, from data every author already declared from the other end — there is
+ *  no field on `CatalogMember` or `CatalogPageInput` for this; a page can never author it directly. */
+export interface AlsoUsedByEntry {
+  /** The other page's or member's own id — its catalog address. */
+  component: string;
+  /** That `ComposedOfEntry`'s own `role`, omitted when it's empty. */
+  role?: string;
+}
+
 /** One row or column heading in a grid. */
 export interface ComparisonAxisItem {
   key: string;
@@ -413,7 +426,11 @@ export interface RelatedPage {
  *  outline — set on `SectionDef.family` by `buildCatalogSections` when a page has `members`. */
 export interface FamilyDef {
   whole: string;
-  members: Array<CatalogMember & { props?: PropDef[]; path: string }>;
+  /** `alsoUsedBy` is derived — `buildCatalogSections` always populates it (`[]` when nothing else
+   *  uses this member) — see `AlsoUsedByEntry`. Optional only so a hand-built `FamilyDef` (a demo,
+   *  a fixture) that predates this field still type-checks; a reader treats an absent value the
+   *  same as `[]`. */
+  members: Array<CatalogMember & { props?: PropDef[]; path: string; alsoUsedBy?: AlsoUsedByEntry[] }>;
   sections: CatalogMemberSection[];
   outline: Map<string, { number: string; level: number }>;
   notShown?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",