@krapwoo/ds-viewer 0.14.2 → 0.16.0

package/native/catalog/TokenLayouts.tsx

@@ -18,7 +18,18 @@ function useWidth(): [number, (event: LayoutChangeEvent) => void] {
  * in up to `columns` columns. A `wide` section takes a full row; the page drops to fewer columns
  * rather than squeeze a section under its minimum width.
  */
-export function TokenSections({ sections, columns, label }: { sections: TokenSection[]; columns: 1 | 2 | 3; label?: string }) {
+export function TokenSections({
+  sections, columns, label, onSectionNode,
+}: {
+  sections: TokenSection[];
+  columns: 1 | 2 | 3;
+  label?: string;
+  /** #64 B2/B5: called with each section's own outer node (web: the real DOM node) as it mounts,
+   *  and `undefined` as it unmounts — keyed by the same id/title React already keys the section
+   *  by. Lets a caller (the jump row, or a section-alias arrival) scroll a given section into view.
+   *  Omitted (every existing caller) leaves every section's own rendering untouched. */
+  onSectionNode?: (key: string, node: unknown) => void;
+}) {
   const [width, onLayout] = useWidth();
   const perRow = sectionColumns(width, columns);
   // Degrading quietly is how a page ends up claiming a column count it never renders: the author
@@ -35,13 +46,23 @@ export function TokenSections({ sections, columns, label }: { sections: TokenSec
   const columnWidth = perRow === 1 ? width : (width - TOKEN_LAYOUT_GAP * (perRow - 1)) / perRow;
   return (
     <View onLayout={onLayout} style={styles.sections}>
-      {width > 0 && sections.map((section) => (
-        <View key={section.title} style={{ width: section.wide || perRow === 1 ? width : columnWidth }}>
-          <Text style={styles.sectionLabel}>{section.title}</Text>
-          {section.desc ? <Text style={styles.sectionDesc}>{section.desc}</Text> : null}
-          <View style={styles.card}>{section.render()}</View>
-        </View>
-      ))}
+      {width > 0 && sections.map((section) => {
+        // #61: `section.id` when the author set one (two sections may legitimately share a human
+        // `title`, e.g. two scoped "Palette" cards — `TokenSection.id`'s own doc comment) — omitted
+        // keeps the prior `title`-keyed behavior exactly as it was.
+        const key = section.id ?? section.title;
+        return (
+          <View
+            key={key}
+            ref={onSectionNode ? (node: unknown) => onSectionNode(key, node) : undefined}
+            style={{ width: section.wide || perRow === 1 ? width : columnWidth }}
+          >
+            <Text style={styles.sectionLabel}>{section.title}</Text>
+            {section.desc ? <Text style={styles.sectionDesc}>{section.desc}</Text> : null}
+            <View style={styles.card}>{section.render()}</View>
+          </View>
+        );
+      })}
     </View>
   );
 }
@@ -64,7 +85,7 @@ export function TokenGrid({ children, minTileWidth = 140, maxColumns }: { childr
  * One token in a `TokenGrid`: its preview, then its name and value, then its role. `note` says
  * where or why the token is used (from its comments or real usages) — omit it when there is none.
  */
-export function TokenTile({ name, value, note, children }: { name: string; value?: string; note?: string; children: React.ReactNode }) {
+export function TokenTile({ name, value, note, children }: { name: string; value?: string; note?: React.ReactNode; children: React.ReactNode }) {
   return (
     <View style={styles.tile}>
       <View style={styles.tilePreview}>{children}</View>

package/native/catalog/catalogNavigation.ts

@@ -157,26 +157,42 @@ export function resolveActiveFromHash<TId extends string>(
 }
 
 /** Where an alias or member id resolves: the family page `pageId`, and — unless it names the
- *  whole itself — the specific `memberId` within it. Built by `aliasTargets`. */
+ *  whole itself — the specific `memberId` within it. Built by `aliasTargets`. #64 B5: a
+ *  tokenDefinition page's section alias instead sets `sectionId` (never together with
+ *  `memberId`), so the page can scroll that section into view on arrival. */
 export interface AliasTarget {
   pageId: string;
   memberId?: string;
+  sectionId?: string;
 }
 
 /** Every member id other than the whole, every member alias, and every family page's own
- *  (page-level) alias, mapped to where it resolves (spec §5.3 "Old addresses"). Pages without a
- *  `family` contribute nothing. */
+ *  (page-level) alias, mapped to where it resolves (spec §5.3 "Old addresses"). #64 B5: also, a
+ *  tokenDefinition page's own page-level aliases (`tokenDefinitionAliases`) and each of its
+ *  sections' own `aliases` — the same routing a family page's aliases already get, extended to
+ *  tokenDefinition pages. A page with neither contributes nothing. */
 export function aliasTargets<TId extends string>(sections: readonly SectionDef<TId>[]): Map<string, AliasTarget> {
   const targets = new Map<string, AliasTarget>();
   for (const section of sections) {
     const family = section.family;
-    if (!family) continue;
-    for (const member of family.members) {
-      if (member.id === family.whole) continue;
-      targets.set(member.id, { pageId: section.id, memberId: member.id });
-      for (const alias of member.aliases ?? []) targets.set(alias, { pageId: section.id, memberId: member.id });
+    if (family) {
+      for (const member of family.members) {
+        if (member.id === family.whole) {
+          // C3: the whole's own id already resolves via `order` (it equals the page's own id), but
+          // its own aliases were never registered anywhere — routing one to the page, with no member
+          // focus (unlike a non-whole member's alias, which focuses that member).
+          for (const alias of member.aliases ?? []) targets.set(alias, { pageId: section.id });
+          continue;
+        }
+        targets.set(member.id, { pageId: section.id, memberId: member.id });
+        for (const alias of member.aliases ?? []) targets.set(alias, { pageId: section.id, memberId: member.id });
+      }
+      for (const alias of family.aliases ?? []) targets.set(alias, { pageId: section.id });
+    }
+    for (const alias of section.tokenDefinitionAliases ?? []) targets.set(alias, { pageId: section.id });
+    for (const tdSection of section.tokenDefinition?.sections ?? []) {
+      for (const alias of tdSection.aliases ?? []) targets.set(alias, { pageId: section.id, sectionId: tdSection.id });
     }
-    for (const alias of family.aliases ?? []) targets.set(alias, { pageId: section.id });
   }
   return targets;
 }
@@ -185,7 +201,10 @@ export function aliasTargets<TId extends string>(sections: readonly SectionDef<T
  *  (kept, unchanged, for existing callers), this never silently falls back to the first page: an
  *  unknown or malformed fragment is reported as `notFound` instead. */
 export type Route<TId extends string> =
-  | { kind: 'page'; id: TId }
+  // #64 B5: `sectionId` is set only when a tokenDefinition page's own section alias resolved here
+  // — the page then scrolls that section into view on arrival. Absent for every other page route,
+  // exactly as before.
+  | { kind: 'page'; id: TId; sectionId?: string }
   | { kind: 'member'; pageId: TId; memberId: string }
   | { kind: 'update' }
   | { kind: 'notFound'; raw: string }
@@ -209,6 +228,7 @@ export function resolveRoute<TId extends string>(
   const target = aliases.get(decoded);
   if (target) {
     if (target.memberId !== undefined) return { kind: 'member', pageId: target.pageId as TId, memberId: target.memberId };
+    if (target.sectionId !== undefined) return { kind: 'page', id: target.pageId as TId, sectionId: target.sectionId };
     return { kind: 'page', id: target.pageId as TId };
   }
   return { kind: 'notFound', raw: decoded };

package/native/catalog/catalogReferences.ts

@@ -0,0 +1,212 @@
+/**
+ * #60 "Source reference" layer — pure data/navigation foundation (plan Task 1). No React or React
+ * Native imports, so it runs under Node's test runner, the same reasoning `catalogNavigation.ts`
+ * documents for itself. Everything here derives from the catalog's own registered `SectionDef[]`
+ * (and the ordering/alias primitives `catalogNavigation.ts` already owns) — never a second,
+ * hand-maintained registry.
+ */
+import type { SectionDef } from './types.ts';
+import type { AliasTarget } from './catalogNavigation.ts';
+
+/** True once any page in the catalog opts into the `'reference'` layer — the controller's trigger
+ *  for showing the separate Source reference affordance at all. A catalog with no such page keeps
+ *  its present sidebar/page set unchanged. */
+export function hasReferenceNavigation<TId extends string>(sections: readonly SectionDef<TId>[]): boolean {
+  return sections.some((section) => section.navigation === 'reference');
+}
+
+/** Every page id whose own `navigation` is not `'reference'` (omitted counts as `'browse'`) — the
+ *  browse-facing subset the sidebar, pager, and hash fallback show. Pass this as `orderedIds`'s own
+ *  `availableIds` to drop reference-only pages from the browse sequence while leaving the complete
+ *  routing universe (every id, alias, and member address) untouched — a reference page, and every
+ *  member of a reference family, stays fully routable; only this browse-facing presentation filter
+ *  ever excludes it. */
+export function browsableIds<TId extends string>(sections: readonly SectionDef<TId>[]): Set<TId> {
+  const ids = new Set<TId>();
+  for (const section of sections) if (section.navigation !== 'reference') ids.add(section.id);
+  return ids;
+}
+
+/** One address the catalog-wide Source reference search can find: a whole page, or (for a family
+ *  page) one of its non-whole members — the whole is never listed twice (see `aliasTargets`'s own
+ *  precedent of skipping the whole among member addresses). `title` is the page's own displayed
+ *  title for a page-level entry, or the member's own id for a member entry (a family member has no
+ *  separate display title of its own, the same convention `MemberSearchEntry`'s `label` already
+ *  uses). `component` is set only from an actual detected binding (`SectionDef.component` /
+ *  `CatalogMember.component`), never guessed. */
+export interface ReferenceEntry<TId extends string = string> {
+  pageId: TId;
+  /** Present only for a family member other than its own whole. */
+  memberId?: string;
+  title: string;
+  component?: string;
+  aliases: readonly string[];
+  /** Authored declaration source, when distinct from the detected implementation path. */
+  source?: string;
+  path: string;
+}
+
+/** Builds the catalog-wide reference index from the registered `SectionDef[]` — one entry per
+ *  page (its own id/title/component/path, plus its family-level aliases, when any), and one per
+ *  non-whole family member (its own id/component/aliases/path). Never a second, hand-authored
+ *  registry: every field here already exists on the runtime catalog record. */
+export function buildReferenceIndex<TId extends string>(sections: readonly SectionDef<TId>[]): ReferenceEntry<TId>[] {
+  const entries: ReferenceEntry<TId>[] = [];
+  for (const section of sections) {
+    const family = section.family;
+    // Family members carry the implementation binding/path and authored declaration source;
+    // section.path may instead point to the catalog page. Keep the whole in the single page entry,
+    // retaining both locations when they differ. Documentation-only wholes keep no binding.
+    // Merge aliases without mutating either authored array.
+    const whole = family?.members.find((member) => member.id === family.whole);
+    entries.push({
+      pageId: section.id,
+      title: section.title ?? section.id,
+      component: whole?.component ?? section.component,
+      aliases: [...new Set([...(family?.aliases ?? []), ...(whole?.aliases ?? [])])],
+      path: whole?.path ?? section.path,
+      ...(whole?.source && whole.source !== (whole.path ?? section.path) ? { source: whole.source } : {}),
+    });
+    if (!family) continue;
+    for (const member of family.members) {
+      if (member.id === family.whole) continue; // the whole already has its own page-level entry above
+      entries.push({
+        pageId: section.id,
+        memberId: member.id,
+        title: member.id,
+        component: member.component,
+        aliases: member.aliases ?? [],
+        path: member.path,
+        ...(member.source !== member.path ? { source: member.source } : {}),
+      });
+    }
+  }
+  return entries;
+}
+
+/** Reference search hits (spec #60's "Search IDs, human titles, component names where known,
+ *  aliases and source paths"): case-insensitive substring over every one of those fields. Mirrors
+ *  `catalogNavigation.ts`'s own `searchResults`/`filterGroups` convention — trimmed, empty query
+ *  returns no hits. */
+export function searchReferenceIndex<TId extends string>(
+  entries: readonly ReferenceEntry<TId>[],
+  query: string,
+): ReferenceEntry<TId>[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  return entries.filter((entry) =>
+    entry.pageId.toLowerCase().includes(q)
+    || (entry.memberId?.toLowerCase().includes(q) ?? false)
+    || entry.title.toLowerCase().includes(q)
+    || (entry.component?.toLowerCase().includes(q) ?? false)
+    || entry.aliases.some((alias) => alias.toLowerCase().includes(q))
+    || (entry.source?.toLowerCase().includes(q) ?? false)
+    || entry.path.toLowerCase().includes(q));
+}
+
+/** Where a name (not a URL fragment — see `catalogNavigation.ts`'s own `resolveRoute` for that)
+ *  resolves, for #60's reference journey: a real address, found to be claimed by more than one
+ *  entry's component binding (never guessed — the caller must say so rather than silently picking
+ *  one), or not found at all. */
+export type ReferenceResolution<TId extends string> =
+  | { kind: 'address'; pageId: TId; memberId?: string }
+  | { kind: 'ambiguous' }
+  | { kind: 'unresolved' };
+
+/** Resolves `name` to its one catalog address: an exact registered page id or member/page alias
+ *  always wins first (reusing the same `order`/`aliases` the viewer's own routing already derives
+ *  — see `catalogNavigation.ts`'s `orderedIds`/`aliasTargets`, never duplicated here), falling back
+ *  to the one unambiguous reference-index entry whose own `component` binding names it. Lets a
+ *  normal page be found by its component export even when that name differs from the page's own
+ *  id — but never invents a new global URL alias from it: a component name shared by more than one
+ *  entry resolves to `'ambiguous'`, not a guess. */
+export function resolveReference<TId extends string>(
+  name: string,
+  order: readonly TId[],
+  aliases: ReadonlyMap<string, AliasTarget>,
+  entries: readonly ReferenceEntry<TId>[],
+): ReferenceResolution<TId> {
+  if ((order as readonly string[]).includes(name)) return { kind: 'address', pageId: name as TId };
+  const aliasTarget = aliases.get(name);
+  if (aliasTarget) return { kind: 'address', pageId: aliasTarget.pageId as TId, memberId: aliasTarget.memberId };
+  const matches = entries.filter((entry) => entry.component === name);
+  if (matches.length === 0) return { kind: 'unresolved' };
+  if (matches.length > 1) return { kind: 'ambiguous' };
+  const [match] = matches;
+  return { kind: 'address', pageId: match.pageId, memberId: match.memberId };
+}
+
+/** Task 2B2: the smallest shared contract `CatalogShell` hands its own ordinary/family renderers
+ *  (`SectionBlock` → `ReferenceDetails`, `FamilyPage`) so an existing reference fact (a Composition
+ *  name, an "also used by" user, a `related`/anatomy name) can become a real, canonical,
+ *  activatable link — through the one accepted resolver above, never a second lookup. Explicit
+ *  props, not a global context: a standalone demo renderer (this very framework's own catalog
+ *  pages included) never receives one unless its own caller passes it, so it can never accidentally
+ *  inherit an outer catalog's registry. Omitted everywhere it's optional — a caller with no
+ *  `navigation` keeps its own prior resolution/activation default untouched (see each call site's
+ *  own doc comment, e.g. `FamilyPage`'s `resolvesAddress`). */
+export interface ReferenceNavigation<TId extends string = string> {
+  /** Resolves `name` to its one real catalog address through `resolveReference`'s own order —
+   *  `undefined` for `'ambiguous'`/`'unresolved'` (never a guess). Method syntax (not a
+   *  property-typed arrow function), deliberately, so a `ReferenceNavigation<TId>` built with the
+   *  catalog's own real union type stays assignable to the plain `ReferenceNavigation` (its default
+   *  `TId = string`) every non-generic internal renderer below this file declares — `FamilyPage.tsx`
+   *  already keeps the same page/member ids as plain `string` once past its own top-level props. */
+  resolve(name: string): { pageId: TId; memberId?: string } | undefined;
+  /** Opens the resolved address through the shell's own real activation, recording the real
+   *  page/member origin and focusing the destination exactly like every other navigation.
+   *  `sourceMemberId`, when supplied, names the family member (or whole) that actually owns the
+   *  activated reference (e.g. a Part's own Uses/related/"also used by" line) — the shell validates
+   *  it against the current page's own family before trusting it, so the recorded origin is the
+   *  part itself rather than just the page. Omitted (a page-level reference, e.g. `relatedPages` or
+   *  an anatomy "other page" entry): the origin is the page alone. */
+  open(pageId: TId, memberId?: string, sourceMemberId?: string): void;
+}
+
+/** `name`'s resolved activation — its real target address plus the activation handler — or
+ *  `undefined` when `navigation` is omitted (the caller's own prior default; never fabricate one)
+ *  or `name` doesn't resolve (honest plain text). One path for every call site that today repeats
+ *  its own "resolve, then build a link" — `ReferenceDetails.tsx`'s Composition facts, and
+ *  `FamilyPage.tsx`'s below-specimens/whole/uses/related-page/anatomy links.
+ *
+ *  Deliberately returns the target, not a ready-made `href` string: this file's own cross-module
+ *  imports (`catalogNavigation.ts`) stay type-only (see the `.ts`-suffixed `import type` above),
+ *  which is what lets it run both under Node's direct `--experimental-strip-types` test execution
+ *  (which requires that suffix on a relative import) and under the published package's own
+ *  consumer-facing bundler typecheck (which forbids a *value* import with that same suffix,
+ *  `allowImportingTsExtensions` being off) — a plain value import of `hashForId` here could only
+ *  ever satisfy one of the two. Every caller is already a `.tsx` file with its own ordinary,
+ *  extension-less `hashForId` import, so building the real `href` (`hashForId(memberId ??
+ *  pageId)`) stays one line at each call site rather than a second, duplicated implementation. */
+/** A modified click (open in a new tab/window) or a non-primary button must reach the browser's
+ *  own anchor handling untouched — the same check `SourceReferencePicker.tsx`'s own `ResultRow`
+ *  already makes for its result links, duplicated here (rather than exported from there) because
+ *  that file is a React component this pure module never imports. */
+function isModifiedPress(event: unknown): boolean {
+  const e = event as { metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean; button?: number } | null | undefined;
+  return Boolean(e?.metaKey || e?.ctrlKey || e?.shiftKey || (typeof e?.button === 'number' && e.button !== 0));
+}
+
+export function referenceLinkProps<TId extends string>(
+  navigation: ReferenceNavigation<TId> | undefined,
+  name: string,
+  /** The family member (or whole) that owns this particular reference, when the call site is
+   *  scoped to one — see `ReferenceNavigation.open`'s own doc comment. */
+  sourceMemberId?: string,
+): { pageId: TId; memberId?: string; onPress: (event?: { preventDefault?: () => void; metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean; button?: number }) => void } | undefined {
+  if (!navigation) return undefined;
+  const target = navigation.resolve(name);
+  if (!target) return undefined;
+  return {
+    pageId: target.pageId,
+    memberId: target.memberId,
+    onPress: (event) => {
+      if (isModifiedPress(event)) return; // let the browser open it in a new tab/window
+      // The shell owns normal activation and its own URL synchronization — the native anchor
+      // default must never race it, embedded or not (an embedded shell additionally never lets
+      // that synchronization touch the host document's own address).
+      event?.preventDefault?.();
+      navigation.open(target.pageId, target.memberId, sourceMemberId);
+    },
+  };
+}

package/native/catalog/familyModel.ts

@@ -53,9 +53,13 @@ export function anatomyPinFor(
   outline: ReadonlyMap<string, { number: string }>,
 ): { number: string; dashed: boolean } | undefined {
   const member = members.get(memberId);
-  if (!member) return undefined;
   const entry = outline.get(memberId);
   if (!entry) return undefined;
+  // #63: an external part is numbered in this family's outline but documented on a group page, so
+  // it isn't in `members`; it keeps its number. Callers that know the owner's fidelity pass it in
+  // `members` (`FamilyDef.externalParts`), so the pin is dashed exactly as an own part's would be;
+  // with none, the pin is the plain solid one.
+  if (!member) return { number: entry.number, dashed: false };
   return { number: entry.number, dashed: member.fidelity === 'documentation-only' };
 }
 
@@ -171,9 +175,11 @@ export function sectionFor(sections: readonly CatalogMemberSection[], memberId:
  *  bad data (a `whole` that isn't one of its own members, already reported by `validateFamily`),
  *  so `FamilyPage` can skip rendering the whole block instead of crashing on an absent member.
  *  Generic over the member's own shape so `FamilyPage` keeps its resolved `props`/`path` fields
- *  (`FamilyDef.members`'s own type) through the lookup. */
-export function resolveWhole<T>(members: ReadonlyMap<string, T>, whole: string): T | undefined {
-  return members.get(whole);
+ *  (`FamilyDef.members`'s own type) through the lookup. #63: `whole` is `undefined` for a group
+ *  page's own `FamilyDef` — degrades the same way, `undefined`, so a group page never renders a
+ *  whole block either (`FamilyPage` itself still never dispatches to a group page in this slice). */
+export function resolveWhole<T>(members: ReadonlyMap<string, T>, whole: string | undefined): T | undefined {
+  return whole === undefined ? undefined : members.get(whole);
 }
 
 /** V2c item 1 (one-shot jump) + item 11 (repeat activation): in-flight state for a member-address

package/native/catalog/index.ts

@@ -18,6 +18,9 @@ export { CatalogSearchInput } from './CatalogSearchInput';
 export { SectionBlock, PagerButton, SectionPagerRow } from './SectionBlock';
 export type { SectionPager } from './SectionBlock';
 export { FamilyPage, AnatomyPin } from './FamilyPage';
+export { GroupPage } from './GroupPage';
+export { JumpRow, JumpChip } from './JumpRow';
+export type { JumpItem } from './JumpRow';
 export { ComparisonGrid } from './ComparisonGrid';
 export { grid, axisItems, axisProp } from './comparison';
 export { ComparisonGroups } from './ComparisonGroups';
@@ -30,12 +33,31 @@ export { MotionSpecimen } from './MotionSpecimen';
 export type { MotionSpecimenProps, MotionSpecimenSpringConfig } from './MotionSpecimen';
 export { SpecimenSurface } from './SpecimenSurface';
 export { TokenSections, TokenGrid, TokenTile } from './TokenLayouts';
+export { StructuredTokenPage, tokenDefinitionSections } from './StructuredTokenPage';
+export {
+  TOKEN_KINDS, isTokenKind, canonicalTokenTitle, findDuplicateIds, tokenEntryAddress,
+  validateTokenDefinition, validateTokenDefinitionUsage,
+} from './tokenDefinition';
+export type {
+  TokenKind, TokenProvenance, TokenResolution, TokenValueInfo, TokenEntryBase, TokenEntry,
+  ColorTokenValue, ColorTokenEntry, DimensionTokenValue, SpacingTokenEntry, RadiusTokenEntry,
+  DimensionsTokenEntry, OpacityTokenValue, OpacityTokenEntry, TypographyTokenValue, TypographyTokenEntry,
+  ShadowTokenValue, ShadowTokenEntry, MotionTimingValue, MotionSpringValue, MotionNativeExpressionValue,
+  MotionTokenValue, MotionTokenEntry, TokenDefinitionSection, TokenDefinition, TokenDefinitionPageUsage,
+} from './tokenDefinition';
 export { DividedStack } from './DividedStack';
 export { Swatch } from './Swatch';
 export { PhoneFrame } from './PhoneFrame';
 export { PhoneScreen } from './PhoneScreen';
 export { OverlayDemo } from './OverlayDemo';
 export { CatalogButton } from './CatalogButton';
+export { SourceReferencePicker } from './SourceReferencePicker';
+export type { SourceReferencePickerProps } from './SourceReferencePicker';
+// #60: only the shape a caller needs to pass real (or, for the self-catalog demo, sample)
+// entries into the picker — `buildReferenceIndex`/`searchReferenceIndex`/`resolveReference` stay
+// internal plumbing for `CatalogShell.tsx`'s own Task 2B wiring, the same precedent Task 1 already
+// established for `catalogReferences.ts`'s other exports.
+export type { ReferenceEntry } from './catalogReferences';
 export { BoundedOverlayViewport } from './BoundedOverlayViewport';
 export type { BoundedOverlayViewportProps } from './BoundedOverlayViewport';
 export { comparisonCellItemKey } from './overlayViewport';