@krapwoo/ds-viewer 0.14.0 → 0.14.1

package/README.md

@@ -427,7 +427,8 @@ path. For anything beyond a single list of tokens, use the token-page layouts be
   alphabetically after the ones that are. The starter kit uses `Tokens`, then every
   component under `Components`, then `Patterns` (whole screens built from the kit, such as
   SavedTrips) and `Reference` (the generated manifest). A larger catalog might add `Recipes` or
-  `Experiences` (full flows) alongside them. Pages sort A–Z inside each group regardless of how
+  `Experiences` (full flows) alongside them. Pages sort A–Z by their displayed title (falling back
+  to their id when they have none; an exact tie breaks on id) inside each group, regardless of how
   many groups you have. Avoid splitting `Components` into finer categories such as "Actions" or
   "Status" purely to browse by — that makes readers guess where a component lives; search and A–Z
   already find it. A distinct semantic group (Tokens vs. Components vs. Patterns) is a different
@@ -444,7 +445,8 @@ path. For anything beyond a single list of tokens, use the token-page layouts be
   usually can't render. Custom replacements styled after a platform control (a custom switch or
   spinner) are not OS components.
 - **Readable titles.** The page id is its address (`#ControlHeights`) and comes from the file
-  name; set `title: 'Control heights'` for the heading, sidebar and search. Pages still sort by id.
+  name; set `title: 'Control heights'` for the heading, sidebar and search. Pages now sort by this
+  title, not the id — so "Control heights" sorts under "C", not under whatever the id starts with.
 - **Point token pages at their token file.** A token page has no component, so its Source would be
   the page file; set `source: 'src/design-system/tokens.ts'` (project-relative) instead.
 - **Coverage only counts the component's own options.** `doctor`'s `option-not-covered` checks

package/dist/native/catalog/catalogNavigation.js

@@ -1,15 +1,32 @@
-/** THE canonical within-group ordering of section ids. */
-export function sortIds(ids) {
-    return ids.slice().sort((a, b) => a.localeCompare(b));
-}
-/** Every page id in sidebar order: groups in declared order, ids sorted within each group,
- *  first occurrence wins, and ids without a matching section (when `availableIds` is given) are
- *  dropped. */
-export function orderedIds(groups, availableIds) {
+/** Fixed English locale, case-insensitive, accent-distinguishing — the one comparator every
+ *  canonical ordering (sidebar, filtered matches, previous/next, hash fallback) shares, so none of
+ *  them can drift against each other. */
+const TITLE_COLLATOR = new Intl.Collator('en', { sensitivity: 'accent' });
+/** THE canonical ordering of two ids: by displayed title (`labels.get(id) ?? id`) first, then —
+ *  for an equal title — by id with the same collator, then by exact code-unit id comparison for
+ *  the rare case where case-insensitive ids also compare equal. */
+function compareCanonical(a, b, labels) {
+    const byTitle = TITLE_COLLATOR.compare(labels?.get(a) ?? a, labels?.get(b) ?? b);
+    if (byTitle !== 0)
+        return byTitle;
+    const byId = TITLE_COLLATOR.compare(a, b);
+    if (byId !== 0)
+        return byId;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** THE canonical within-group ordering of section ids: by each id's displayed title
+ *  (`SectionDef.title`, via `labels`), falling back to the id itself when a page has no title. */
+export function sortIds(ids, labels) {
+    return ids.slice().sort((a, b) => compareCanonical(a, b, labels));
+}
+/** Every page id in sidebar order: groups in declared order, ids sorted within each group (by
+ *  displayed title, via `labels`), first occurrence wins, and ids without a matching section (when
+ *  `availableIds` is given) are dropped. */
+export function orderedIds(groups, availableIds, labels) {
     const seen = new Set();
     const order = [];
     for (const group of groups) {
-        for (const id of sortIds(group.ids)) {
+        for (const id of sortIds(group.ids, labels)) {
             if (seen.has(id))
                 continue;
             if (availableIds && !availableIds.has(id))
@@ -46,7 +63,7 @@ memberIds) {
         label: group.label,
         ids: sortIds(q ? group.ids.filter((id) => id.toLowerCase().includes(q)
             || (labels?.get(id)?.toLowerCase().includes(q) ?? false)
-            || (memberIds?.get(id)?.some((memberId) => memberId.toLowerCase().includes(q)) ?? false)) : group.ids),
+            || (memberIds?.get(id)?.some((memberId) => memberId.toLowerCase().includes(q)) ?? false)) : group.ids, labels),
     }))
         .filter((group) => group.ids.length > 0);
 }

package/native/catalog/CatalogShell.tsx

@@ -221,7 +221,7 @@ export function CatalogShell<TId extends string>({
 
   const sectionsById = useMemo(() => new Map(sections.map((def) => [def.id, def])), [sections]);
   const labels = useMemo(() => new Map(sections.filter((def) => def.title).map((def) => [def.id as string, def.title as string])), [sections]);
-  const order = useMemo(() => orderedIds(groups, new Set(sectionsById.keys())), [groups, sectionsById]);
+  const order = useMemo(() => orderedIds(groups, new Set(sectionsById.keys()), labels), [groups, sectionsById, labels]);
   // Spec §5.3: every family page's own member ids/aliases, resolved to their page (and member, for
   // anything other than the whole) — used both for an old/alias/member address (`resolveRoute`)
   // and for the sidebar's member search (`memberSearchEntries` below).

package/native/catalog/catalogNavigation.ts

@@ -5,22 +5,40 @@
  */
 import type { NavGroup, SectionDef, UpdateNotice, VersionStatus } from './types.ts';
 
-/** THE canonical within-group ordering of section ids. */
-export function sortIds<TId extends string>(ids: readonly TId[]): TId[] {
-  return ids.slice().sort((a, b) => a.localeCompare(b));
+/** Fixed English locale, case-insensitive, accent-distinguishing — the one comparator every
+ *  canonical ordering (sidebar, filtered matches, previous/next, hash fallback) shares, so none of
+ *  them can drift against each other. */
+const TITLE_COLLATOR = new Intl.Collator('en', { sensitivity: 'accent' });
+
+/** THE canonical ordering of two ids: by displayed title (`labels.get(id) ?? id`) first, then —
+ *  for an equal title — by id with the same collator, then by exact code-unit id comparison for
+ *  the rare case where case-insensitive ids also compare equal. */
+function compareCanonical<TId extends string>(a: TId, b: TId, labels?: ReadonlyMap<string, string>): number {
+  const byTitle = TITLE_COLLATOR.compare(labels?.get(a) ?? a, labels?.get(b) ?? b);
+  if (byTitle !== 0) return byTitle;
+  const byId = TITLE_COLLATOR.compare(a, b);
+  if (byId !== 0) return byId;
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** THE canonical within-group ordering of section ids: by each id's displayed title
+ *  (`SectionDef.title`, via `labels`), falling back to the id itself when a page has no title. */
+export function sortIds<TId extends string>(ids: readonly TId[], labels?: ReadonlyMap<string, string>): TId[] {
+  return ids.slice().sort((a, b) => compareCanonical(a, b, labels));
 }
 
-/** Every page id in sidebar order: groups in declared order, ids sorted within each group,
- *  first occurrence wins, and ids without a matching section (when `availableIds` is given) are
- *  dropped. */
+/** Every page id in sidebar order: groups in declared order, ids sorted within each group (by
+ *  displayed title, via `labels`), first occurrence wins, and ids without a matching section (when
+ *  `availableIds` is given) are dropped. */
 export function orderedIds<TId extends string>(
   groups: readonly NavGroup<TId>[],
   availableIds?: ReadonlySet<TId>,
+  labels?: ReadonlyMap<string, string>,
 ): TId[] {
   const seen = new Set<TId>();
   const order: TId[] = [];
   for (const group of groups) {
-    for (const id of sortIds(group.ids)) {
+    for (const id of sortIds(group.ids, labels)) {
       if (seen.has(id)) continue;
       if (availableIds && !availableIds.has(id)) continue;
       seen.add(id);
@@ -65,7 +83,7 @@ export function filterGroups<TId extends string>(
         id.toLowerCase().includes(q)
         || (labels?.get(id)?.toLowerCase().includes(q) ?? false)
         || (memberIds?.get(id)?.some((memberId) => memberId.toLowerCase().includes(q)) ?? false),
-      ) : group.ids),
+      ) : group.ids, labels),
     }))
     .filter((group) => group.ids.length > 0);
 }

package/package.json

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