@krapwoo/ds-viewer 0.14.2 → 0.16.0

package/dist/cli/staticPage.js

@@ -1,5 +1,6 @@
 import * as ts from 'typescript';
 import { readFileSync } from 'node:fs';
+import { readStaticTokenDefinition } from "./tokenDefinition.js";
 const TRANSPILE_OPTIONS = {
     compilerOptions: { jsx: ts.JsxEmit.ReactJSX, module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
     reportDiagnostics: true,
@@ -58,21 +59,26 @@ function readStaticPage(file) {
         return { file, checkable: false, viewerImports };
     const page = { file, checkable: true, viewerImports };
     const idProp = findProp(pageObject, 'id');
+    const titleProp = findProp(pageObject, 'title');
     const componentProp = findProp(pageObject, 'component');
     const groupProp = findProp(pageObject, 'group');
     const specimenSizeProp = findProp(pageObject, 'specimenSize');
     const tokenGalleryProp = findProp(pageObject, 'tokenGallery');
     if (idProp)
         page.id = stringLiteral(resolve(idProp.initializer, consts, new Set()));
+    if (titleProp)
+        page.title = stringLiteral(resolve(titleProp.initializer, consts, new Set()));
     if (componentProp)
         page.component = stringLiteral(resolve(componentProp.initializer, consts, new Set()));
     if (groupProp)
         page.group = stringLiteral(resolve(groupProp.initializer, consts, new Set()));
     if (specimenSizeProp)
         page.specimenSize = stringLiteral(resolve(specimenSizeProp.initializer, consts, new Set()));
+    page.hasExplicitTokenGallery = tokenGalleryProp !== undefined;
     if (tokenGalleryProp)
         page.tokenGallery = resolve(tokenGalleryProp.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword;
     const tokenSectionsProp = findProp(pageObject, 'tokenSections');
+    page.hasExplicitTokenSections = tokenSectionsProp !== undefined;
     if (tokenSectionsProp) {
         const list = resolve(tokenSectionsProp.initializer, consts, new Set());
         const items = ts.isArrayLiteralExpression(list) ? list.elements.map((element) => resolve(element, consts, new Set())) : [list];
@@ -201,6 +207,7 @@ function readStaticPage(file) {
         }
     }
     const membersProp = findProp(pageObject, 'members');
+    page.hasMembers = membersProp !== undefined;
     if (membersProp) {
         const members = readFamilyMembers(membersProp.initializer, consts, gridNames, sourceFile);
         if (!members)
@@ -209,6 +216,7 @@ function readStaticPage(file) {
             page.members = members;
     }
     const wholeProp = findProp(pageObject, 'whole');
+    page.hasWhole = wholeProp !== undefined;
     if (wholeProp) {
         const whole = stringLiteral(resolve(wholeProp.initializer, consts, new Set()));
         if (whole === undefined)
@@ -217,6 +225,7 @@ function readStaticPage(file) {
             page.whole = whole;
     }
     const sectionsProp = findProp(pageObject, 'sections');
+    page.hasSections = sectionsProp !== undefined;
     if (sectionsProp) {
         const sectionsRead = readSections(sectionsProp.initializer, consts);
         if (!sectionsRead)
@@ -235,11 +244,46 @@ function readStaticPage(file) {
     const relatedPagesProp = findProp(pageObject, 'relatedPages');
     if (relatedPagesProp)
         page.relatedPages = readRelatedPages(relatedPagesProp.initializer, consts);
+    page.hasAnatomy = findProp(pageObject, 'anatomy') !== undefined;
+    const navigationProp = findProp(pageObject, 'navigation');
+    if (navigationProp) {
+        const resolved = resolve(navigationProp.initializer, consts, new Set());
+        if (ts.isStringLiteral(resolved) && (resolved.text === 'browse' || resolved.text === 'reference')) {
+            page.navigation = resolved.text;
+        }
+        else {
+            page.checkable = false;
+        }
+    }
+    const standaloneProp = findProp(pageObject, 'standalone');
+    if (standaloneProp)
+        page.standalone = stringLiteral(resolve(standaloneProp.initializer, consts, new Set()));
+    const tokenDefinitionProp = findProp(pageObject, 'tokenDefinition');
+    page.hasTokenDefinition = tokenDefinitionProp !== undefined;
+    if (tokenDefinitionProp) {
+        const tokenDefinition = readStaticTokenDefinition(tokenDefinitionProp.initializer, consts);
+        if (!tokenDefinition)
+            page.checkable = false;
+        else {
+            page.tokenDefinition = tokenDefinition;
+            // #61 geometry parity (design R4): the same titles/wide flags `buildCatalogSections` derives
+            // at runtime from `tokenDefinition.sections` — only when no separate `tokenSections` already
+            // set them (an explicit conflict is reported on its own terms by `cli/doctor.ts`; whichever
+            // geometry already won here doesn't change that).
+            if (page.tokenSectionTitles === undefined) {
+                page.tokenSectionTitles = tokenDefinition.sections.map((section) => section.title);
+                page.tokenSectionWide = tokenDefinition.sections.map((section) => section.wide ?? false);
+                page.tokenGallery = true;
+            }
+        }
+    }
     return page;
 }
 /** A literal array of string literals (or same-file `const` references to one) — undefined for
- *  anything else, including an array containing even one non-literal element. */
-function readStringLiteralArray(node, consts) {
+ *  anything else, including an array containing even one non-literal element. Exported for
+ *  `cli/tokenDefinition.ts`'s own static read of a tokenDefinition section's `aliases` (#64 B5),
+ *  the same leniency every other string-literal-array field here already gets. */
+export function readStringLiteralArray(node, consts) {
     const resolved = resolve(node, consts, new Set());
     if (!ts.isArrayLiteralExpression(resolved))
         return undefined;
@@ -295,15 +339,19 @@ function readFamilyMembers(node, consts, gridNames, sourceFile) {
             if (!comparison)
                 return undefined;
         }
+        const anatomyProp = findProp(resolvedElement, 'anatomy');
+        const memberIds = anatomyProp ? readAnatomyMemberIds(anatomyProp.initializer, consts) : undefined;
         members.push({
             id,
             component,
             parent,
             aliases,
             composedOf,
+            hasComposedOf: composedOfProp !== undefined,
             hasWhenToUse: findProp(resolvedElement, 'whenToUse') !== undefined,
             hasA11y: findProp(resolvedElement, 'a11y') !== undefined,
             hasExamples: Boolean(variants.items?.length) || Boolean(states.items?.length) || Boolean(comparison),
+            anatomy: memberIds ? { memberIds } : undefined,
         });
     }
     return members;
@@ -339,9 +387,9 @@ function readSections(node, consts) {
     }
     return sections;
 }
-/** A literal array of `ComposedOfEntry`-shaped object literals, read down to just `component`
- *  (design §4: role/relationship are authored prose `doctor` never needs for its missing-
- *  composition comparison). Undefined — not an empty array — for anything that isn't itself a
+/** A literal array of `ComposedOfEntry`-shaped object literals, read down to `component` and a
+ *  literal `relationship` (a non-literal one is left off the entry; `role` is authored prose
+ *  `doctor` never needs). Undefined — not an empty array — for anything that isn't itself a
  *  literal array, or whose element isn't an object literal with a literal `component`: `doctor`
  *  must never mistake "couldn't read this" for "author declared no composition here". */
 function readComposedOf(node, consts) {
@@ -356,10 +404,51 @@ function readComposedOf(node, consts) {
         const component = propertyStringLiteral(resolvedElement, 'component', consts);
         if (component === undefined)
             return undefined;
-        entries.push({ component });
+        const relationship = propertyStringLiteral(resolvedElement, 'relationship', consts);
+        entries.push(relationship === undefined ? { component } : { component, relationship });
     }
     return entries;
 }
+/** #63 A4/A10: `CatalogMember.anatomy`/`CatalogPageInput.anatomy`'s own `groups[].items[]`, read
+ *  down to just the literal `member` ids a `{ member: string }` item names — an `{ other: string }`
+ *  item is skipped (it never names a descendant), and `description`/`picture` are never read (design
+ *  parity with `readComposedOf`/`readRelatedPages`: `doctor`'s own rule never needs them). Undefined
+ *  — never a partial read — for anything that isn't itself a literal `{ groups: [...] }` object with
+ *  a literal `groups` array of literal `{ items: [...] }` objects whose own `items` array is itself
+ *  literal; an `other`/`description`-shaped item still reads fine even though its own `member` (if
+ *  any) is simply absent from the result. */
+function readAnatomyMemberIds(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isObjectLiteralExpression(resolved))
+        return undefined;
+    const groupsProp = findProp(resolved, 'groups');
+    if (!groupsProp)
+        return undefined;
+    const groupsResolved = resolve(groupsProp.initializer, consts, new Set());
+    if (!ts.isArrayLiteralExpression(groupsResolved))
+        return undefined;
+    const memberIds = [];
+    for (const groupElement of groupsResolved.elements) {
+        const group = resolve(groupElement, consts, new Set());
+        if (!ts.isObjectLiteralExpression(group))
+            return undefined;
+        const itemsProp = findProp(group, 'items');
+        if (!itemsProp)
+            return undefined;
+        const itemsResolved = resolve(itemsProp.initializer, consts, new Set());
+        if (!ts.isArrayLiteralExpression(itemsResolved))
+            return undefined;
+        for (const itemElement of itemsResolved.elements) {
+            const item = resolve(itemElement, consts, new Set());
+            if (!ts.isObjectLiteralExpression(item))
+                return undefined;
+            const member = propertyStringLiteral(item, 'member', consts);
+            if (member !== undefined)
+                memberIds.push(member);
+        }
+    }
+    return memberIds;
+}
 /** A literal array of `RelatedPage`-shaped object literals, read down to just `page` (design
  *  parity with `readComposedOf`: `note` is authored prose `doctor` never needs). Undefined — not
  *  an empty array — for anything that isn't itself a literal array, or whose element isn't an
@@ -433,7 +522,7 @@ function topLevelConsts(sourceFile) {
  *  reference to its own initializer (same pattern as `cli/tokens.ts`'s `readExpression`) — returns
  *  the resolved expression node itself, not a value, so callers can pattern-match on its kind
  *  (array/object literal, call expression, …). `seen` guards a reference cycle. */
-function resolve(node, consts, seen) {
+export function resolve(node, consts, seen) {
     if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node)) {
         return resolve(node.expression, consts, seen);
     }
@@ -444,7 +533,7 @@ function resolve(node, consts, seen) {
     }
     return node;
 }
-function stringLiteral(node) {
+export function stringLiteral(node) {
     return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : undefined;
 }
 /** `true`/`false` only from a known `true`/`false` literal; any other expression (a variable, a
@@ -464,11 +553,11 @@ function literalBooleanOrUnknown(node, consts) {
 function propertyName(name) {
     return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : name.getText();
 }
-function findProp(obj, name) {
+export function findProp(obj, name) {
     const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) && propertyName(p.name) === name);
     return prop;
 }
-function propertyStringLiteral(obj, name, consts) {
+export function propertyStringLiteral(obj, name, consts) {
     const prop = findProp(obj, name);
     return prop ? stringLiteral(resolve(prop.initializer, consts, new Set())) : undefined;
 }

package/dist/cli/tokenDefinition.js

@@ -0,0 +1,125 @@
+/**
+ * Static, literal-only reader for `CatalogPageInput.tokenDefinition` — the same posture
+ * `cli/staticPage.ts`'s own `readStaticPage` already uses for every other field: no module
+ * resolution, no execution, a same-file `const` chase only (`resolve`, reused from
+ * `cli/staticPage.ts`). Reads structural metadata only (`kind`, section `id`/`title`/`desc`/`wide`,
+ * and each entry's own literal `id`, for duplicate detection) — never an entry's real value, which
+ * stays an opaque runtime import (design R4).
+ */
+import * as ts from 'typescript';
+import { findProp, propertyStringLiteral, readStringLiteralArray, resolve } from "./staticPage.js";
+import { canonicalTokenTitle, isTokenKind } from "../native/catalog/tokenDefinition.js";
+/** Reads `node` (a `tokenDefinition:` property initializer) down to `kind` and each section's
+ *  `id`/`title`/`desc`/`wide`/entry-ids. Returns `undefined` — never a partial read — when `kind`
+ *  isn't a literal, `sections` isn't a literal array, or any one section isn't a literal object
+ *  with a literal `id` and `title`: the same "never a partial read" contract every other array
+ *  reader in `cli/staticPage.ts` already follows (`readComposedOf`, `readSections`, …). An entry
+ *  whose own `id` isn't literal is simply omitted from `entryIds` — informational leniency, since
+ *  only the *structural* shape (kind/sections/ids) needs to be checkable, never an entry's real
+ *  value (design R4: "no blanket uncheckability of otherwise literal page geometry"). */
+export function readStaticTokenDefinition(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isObjectLiteralExpression(resolved))
+        return undefined;
+    const kind = propertyStringLiteral(resolved, 'kind', consts);
+    if (kind === undefined)
+        return undefined;
+    const sectionsProp = findProp(resolved, 'sections');
+    if (!sectionsProp)
+        return undefined;
+    const sectionsResolved = resolve(sectionsProp.initializer, consts, new Set());
+    if (!ts.isArrayLiteralExpression(sectionsResolved))
+        return undefined;
+    const sections = [];
+    for (const element of sectionsResolved.elements) {
+        const sectionResolved = resolve(element, consts, new Set());
+        if (!ts.isObjectLiteralExpression(sectionResolved))
+            return undefined;
+        const id = propertyStringLiteral(sectionResolved, 'id', consts);
+        const title = propertyStringLiteral(sectionResolved, 'title', consts);
+        if (id === undefined || title === undefined)
+            return undefined;
+        const desc = propertyStringLiteral(sectionResolved, 'desc', consts);
+        const wideProp = findProp(sectionResolved, 'wide');
+        const wide = wideProp ? resolve(wideProp.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword : false;
+        const entryIds = [];
+        let entriesOpaque = false;
+        const entriesProp = findProp(sectionResolved, 'entries');
+        if (entriesProp) {
+            const entriesResolved = resolve(entriesProp.initializer, consts, new Set());
+            if (ts.isArrayLiteralExpression(entriesResolved)) {
+                for (const entryElement of entriesResolved.elements) {
+                    const entryResolved = resolve(entryElement, consts, new Set());
+                    if (!ts.isObjectLiteralExpression(entryResolved)) {
+                        entriesOpaque = true;
+                        continue;
+                    }
+                    const entryId = propertyStringLiteral(entryResolved, 'id', consts);
+                    if (entryId !== undefined)
+                        entryIds.push(entryId);
+                    else
+                        entriesOpaque = true;
+                }
+            }
+            else {
+                entriesOpaque = true;
+            }
+        }
+        // #64 B1: this section's own sub-groups, read the same lenient way as its own entries above.
+        const groups = [];
+        let groupsOpaque = false;
+        const groupsProp = findProp(sectionResolved, 'groups');
+        if (groupsProp) {
+            const groupsResolved = resolve(groupsProp.initializer, consts, new Set());
+            if (ts.isArrayLiteralExpression(groupsResolved)) {
+                for (const groupElement of groupsResolved.elements) {
+                    const groupResolved = resolve(groupElement, consts, new Set());
+                    if (!ts.isObjectLiteralExpression(groupResolved)) {
+                        groupsOpaque = true;
+                        continue;
+                    }
+                    const groupId = propertyStringLiteral(groupResolved, 'id', consts);
+                    const groupTitle = propertyStringLiteral(groupResolved, 'title', consts);
+                    if (groupId === undefined || groupTitle === undefined) {
+                        groupsOpaque = true;
+                        continue;
+                    }
+                    const groupEntryIds = [];
+                    let groupEntriesOpaque = false;
+                    const groupEntriesProp = findProp(groupResolved, 'entries');
+                    if (groupEntriesProp) {
+                        const groupEntriesResolved = resolve(groupEntriesProp.initializer, consts, new Set());
+                        if (ts.isArrayLiteralExpression(groupEntriesResolved)) {
+                            for (const entryElement of groupEntriesResolved.elements) {
+                                const entryResolved = resolve(entryElement, consts, new Set());
+                                if (!ts.isObjectLiteralExpression(entryResolved)) {
+                                    groupEntriesOpaque = true;
+                                    continue;
+                                }
+                                const entryId = propertyStringLiteral(entryResolved, 'id', consts);
+                                if (entryId !== undefined)
+                                    groupEntryIds.push(entryId);
+                                else
+                                    groupEntriesOpaque = true;
+                            }
+                        }
+                        else {
+                            groupEntriesOpaque = true;
+                        }
+                    }
+                    groups.push({ id: groupId, title: groupTitle, entryIds: groupEntryIds, entriesOpaque: groupEntriesOpaque });
+                }
+            }
+            else {
+                groupsOpaque = true;
+            }
+        }
+        // #64 B5: this section's own literal `aliases`, when every element resolves as a literal
+        // string — omitted (never a penalty) otherwise.
+        const aliasesProp = findProp(sectionResolved, 'aliases');
+        const aliases = aliasesProp ? readStringLiteralArray(aliasesProp.initializer, consts) : undefined;
+        sections.push({ id, title, desc, wide, entryIds, entriesOpaque, groups, groupsOpaque, ...(aliases !== undefined ? { aliases } : null) });
+    }
+    return { kind, sections };
+}
+export { canonicalTokenTitle, isTokenKind };

package/dist/native/catalog/catalogNavigation.js

@@ -132,23 +132,37 @@ export function resolveActiveFromHash(hash, order) {
     return idFromHash(hash, order);
 }
 /** 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(sections) {
     const targets = new Map();
     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 family.aliases ?? [])
+        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 });
+        }
     }
     return targets;
 }
@@ -171,6 +185,8 @@ export function resolveRoute(hash, order, aliases) {
     if (target) {
         if (target.memberId !== undefined)
             return { kind: 'member', pageId: target.pageId, memberId: target.memberId };
+        if (target.sectionId !== undefined)
+            return { kind: 'page', id: target.pageId, sectionId: target.sectionId };
         return { kind: 'page', id: target.pageId };
     }
     return { kind: 'notFound', raw: decoded };