@krapwoo/ds-viewer 0.14.2 → 0.16.0

package/dist/native/catalog/tokenDefinition.js

@@ -0,0 +1,205 @@
+/**
+ * Pure data model for `CatalogPageInput.tokenDefinition` — an optional, opt-in structured shape for
+ * a token page's real entries (name, value, provenance, source) instead of a hand-built `render()`.
+ * No React or React Native import: this module is shared by the runtime (`pageApi.ts`), the real
+ * renderer (`StructuredTokenPage.tsx`), and the CLI's static reader (`cli/tokenDefinition.ts`), and
+ * is itself tested directly under the plain Node `--experimental-strip-types` runner.
+ *
+ * Omitting `tokenDefinition` leaves every existing `tokenGallery`/`tokenSections`/`render` page
+ * exactly as it was — nothing here changes unless a page opts in.
+ */
+export const TOKEN_KINDS = ['colors', 'typography', 'spacing', 'radius', 'dimensions', 'shadows', 'opacity', 'motion'];
+const TOKEN_KIND_TITLES = {
+    colors: 'Colors',
+    typography: 'Typography',
+    spacing: 'Spacing',
+    radius: 'Radius',
+    dimensions: 'Dimensions',
+    shadows: 'Shadows',
+    opacity: 'Opacity',
+    motion: 'Motion',
+};
+export function isTokenKind(value) {
+    return Object.prototype.hasOwnProperty.call(TOKEN_KIND_TITLES, value);
+}
+/** The one fixed title a kind renders under — an opted-in page's own explicit `title` must equal
+ *  this (see `validateTokenDefinitionUsage`), or omit `title` entirely to get it for free. */
+export function canonicalTokenTitle(kind) {
+    return TOKEN_KIND_TITLES[kind];
+}
+const TOKEN_PROVENANCE_LABELS = {
+    named: 'Named token',
+    inline: 'Inline value',
+    platform: 'Platform-provided',
+    'unresolved-finding': 'Unresolved finding',
+};
+/** The fixed caption vocabulary for a value's own `provenance`/`named` pair — plain muted caption
+ *  text, never a status badge (correction C1: provenance must be visible, but never as a pill/tag).
+ *  Appends " · named token" only when `named` is true (`TokenValueInfo.named`'s own doc comment:
+ *  meaningful only alongside `'platform'`/`'unresolved-finding'`). */
+export function tokenProvenanceCaption(value) {
+    const label = TOKEN_PROVENANCE_LABELS[value.provenance];
+    return value.named ? `${label} · named token` : label;
+}
+/** When every one of `entries` shares the same `tokenProvenanceCaption`, returns it once — the
+ *  renderer's own section-level consolidation (correction C1: show a shared provenance+named pair
+ *  once under the section instead of repeating it on every entry). `undefined` for an empty list,
+ *  or when the entries disagree — either way the caller shows it per entry instead. */
+export function consolidatedProvenanceCaption(entries) {
+    if (entries.length === 0)
+        return undefined;
+    const first = tokenProvenanceCaption(entries[0].value);
+    return entries.every((entry) => tokenProvenanceCaption(entry.value) === first) ? first : undefined;
+}
+/** #64 B2 / review F5: how many values a section shows — the count the jump row's chip reads. It is
+ *  computed from the same pipeline the renderer uses (`renderedEntryCount`): ids deduplicated within
+ *  each list, entries of another `kind` dropped, then light/dark pairing, over the section's own
+ *  `entries` plus every one of its `groups'` own `entries`. */
+export function sectionEntryCount(kind, section) {
+    const groupTotal = (section.groups ?? []).reduce((sum, group) => sum + renderedEntryCount(kind, group.entries), 0);
+    return renderedEntryCount(kind, section.entries) + groupTotal;
+}
+/** Every id that appears more than once in `ids`, each listed once. Order-independent; used both for
+ *  a section's own entry ids (must be unique within that section — ids may still recur in a
+ *  *different* section, see `TokenEntryBase.id`) and for a definition's own section ids. */
+export function findDuplicateIds(ids) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const id of ids) {
+        if (seen.has(id))
+            duplicates.add(id);
+        seen.add(id);
+    }
+    return [...duplicates];
+}
+/** A collision-safe address for one entry: page, section, and entry id joined so that an escaped
+ *  separator inside any one of the three can never be mistaken for a real boundary (`/` and `\`
+ *  are escaped before joining) — never a flattened/concatenated name. Used wherever an entry needs
+ *  one stable cross-page identity (future search/manifest indexing); not required for a React list
+ *  key, which only ever needs sibling-level uniqueness. */
+export function tokenEntryAddress(pageId, sectionId, entryId) {
+    const encode = (part) => part.replace(/\\/g, '\\\\').replace(/\//g, '\\/');
+    return `${encode(pageId)}/${encode(sectionId)}/${encode(entryId)}`;
+}
+/** Structural problems with a `TokenDefinition` itself (design, Global Constraints: "never a
+ *  partial read/silent precedence loss") — duplicate section ids, a section with duplicate entry
+ *  ids, or an entry whose own `kind` doesn't match the page's declared `kind`. Empty when the
+ *  definition is internally consistent. Both `buildCatalogSections` (dev console) and
+ *  `cli/doctor.ts` (CI-failing errors) call this so the same rule applies at runtime and statically. */
+export function validateTokenDefinition(def) {
+    const issues = [];
+    for (const id of findDuplicateIds(def.sections.map((s) => s.id))) {
+        issues.push(`tokenDefinition has more than one section with id "${id}".`);
+    }
+    for (const section of def.sections) {
+        for (const id of findDuplicateIds(section.entries.map((e) => e.id))) {
+            issues.push(`tokenDefinition section "${section.id}" has more than one entry with id "${id}".`);
+        }
+        for (const entry of section.entries) {
+            if (entry.kind !== def.kind) {
+                issues.push(`tokenDefinition section "${section.id}": entry "${entry.id}" has kind "${entry.kind}", but the page's kind is "${def.kind}".`);
+            }
+        }
+        // #64 B1: a section's own `groups` — group ids unique within the section, entry ids unique
+        // within their own group (a separate scope from the section's own entries and every other
+        // group), and the same kind-match rule as the section's own entries.
+        for (const id of findDuplicateIds((section.groups ?? []).map((g) => g.id))) {
+            issues.push(`tokenDefinition section "${section.id}" has more than one group with id "${id}".`);
+        }
+        for (const group of section.groups ?? []) {
+            for (const id of findDuplicateIds(group.entries.map((e) => e.id))) {
+                issues.push(`tokenDefinition section "${section.id}" group "${group.id}" has more than one entry with id "${id}".`);
+            }
+            for (const entry of group.entries) {
+                if (entry.kind !== def.kind) {
+                    issues.push(`tokenDefinition section "${section.id}" group "${group.id}": entry "${entry.id}" has kind "${entry.kind}", but the page's kind is "${def.kind}".`);
+                }
+            }
+        }
+    }
+    return issues;
+}
+export function pairLightDarkColorEntries(entries) {
+    const lightByName = new Map();
+    const darkByName = new Map();
+    for (const entry of entries) {
+        if (entry.appearance === 'light' && !lightByName.has(entry.name))
+            lightByName.set(entry.name, entry);
+        if (entry.appearance === 'dark' && !darkByName.has(entry.name))
+            darkByName.set(entry.name, entry);
+    }
+    const claimed = new Set();
+    const result = [];
+    for (const entry of entries) {
+        if (claimed.has(entry.id))
+            continue;
+        if (entry.appearance === 'light') {
+            const dark = darkByName.get(entry.name);
+            if (dark && dark.id !== entry.id && !claimed.has(dark.id)) {
+                claimed.add(entry.id);
+                claimed.add(dark.id);
+                result.push({ kind: 'pair', name: entry.name, light: entry, dark });
+                continue;
+            }
+        }
+        if (entry.appearance === 'dark') {
+            const light = lightByName.get(entry.name);
+            if (light && light.id !== entry.id && !claimed.has(light.id)) {
+                claimed.add(entry.id);
+                claimed.add(light.id);
+                result.push({ kind: 'pair', name: entry.name, light, dark: entry });
+                continue;
+            }
+        }
+        result.push({ kind: 'single', entry });
+    }
+    return result;
+}
+/** The real entries of one list, deduplicated by id within this kind — shared by the section's own
+ *  `entries` and, #64 B1, each of its `groups`' own `entries` (a separate scope per group), so none
+ *  of them ever double-counts an entry whose own `kind` doesn't match (already reported by
+ *  `validateTokenDefinition`) or whose `id` repeats another entry in the *same* list. The renderer
+ *  and the jump row's chip count both read through this. */
+export function filteredKindEntriesFromList(kind, entries) {
+    const seen = new Set();
+    return entries.filter((entry) => {
+        if (entry.kind !== kind)
+            return false;
+        if (seen.has(entry.id))
+            return false;
+        seen.add(entry.id);
+        return true;
+    });
+}
+/** Whether a light/dark pair can render as one split swatch. A pair whose light or dark side has no
+ *  real drawable value (unresolved) can't, and falls back to each entry's own cell. */
+export function pairRendersAsOneSwatch(light, dark) {
+    return light.value.resolution.status === 'resolved' && dark.value.resolution.status === 'resolved';
+}
+/** How many cells one entries list renders: the filtered list, with a resolved light/dark pair as
+ *  one swatch and an unresolved pair as two. */
+export function renderedEntryCount(kind, entries) {
+    const shown = filteredKindEntriesFromList(kind, entries);
+    if (kind !== 'colors')
+        return shown.length;
+    return pairLightDarkColorEntries(shown).reduce((count, item) => count + (item.kind === 'pair' && !pairRendersAsOneSwatch(item.light, item.dark) ? 2 : 1), 0);
+}
+/** Actionable conflicts between an opted-in `tokenDefinition` and the rest of the page it sits on
+ *  (design R1: "never silent precedence/data loss") — an explicit legacy `render`/`tokenGallery`/
+ *  `tokenSections`, an incompatible family (`members`) recipe, or an explicit `title` that doesn't
+ *  match the kind's canonical title. Empty when there is nothing to report. */
+export function validateTokenDefinitionUsage(kind, usage) {
+    const issues = [];
+    if (usage.hasRender)
+        issues.push('tokenDefinition conflicts with this page\'s own "render" — remove one of them.');
+    if (usage.hasTokenGallery)
+        issues.push('tokenDefinition conflicts with this page\'s own "tokenGallery" — remove one of them.');
+    if (usage.hasTokenSections)
+        issues.push('tokenDefinition conflicts with this page\'s own "tokenSections" — remove one of them.');
+    if (usage.hasFamily)
+        issues.push('tokenDefinition conflicts with this page\'s own "members" (a family page) — remove one of them.');
+    if (usage.title !== undefined && usage.title !== canonicalTokenTitle(kind)) {
+        issues.push(`tokenDefinition: title "${usage.title}" conflicts with kind "${kind}" (expected "${canonicalTokenTitle(kind)}"). Omit "title" to use it automatically.`);
+    }
+    return issues;
+}

package/native/catalog/CatalogSearchInput.tsx

@@ -1,4 +1,4 @@
-import { useRef, useState } from 'react';
+import { useRef, useState, type RefObject } from 'react';
 import { View, Text, TextInput, Pressable, StyleSheet } from 'react-native';
 import { CATALOG_TEXT, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS, CATALOG_LAYOUT } from './tokens';
 
@@ -7,15 +7,28 @@ import { CATALOG_TEXT, CATALOG_COLOR, CATALOG_SPACE, CATALOG_RADIUS, CATALOG_LAY
  * RN primitives rather than the host app's own search/field component — the catalog is a
  * documentation tool for that component, not a consumer of it, so its own chrome shouldn't depend
  * on (or accidentally break alongside) whatever that component does.
+ *
+ * `accessibilityLabel` and `autoFocus` are optional and additive (#60): every existing caller
+ * keeps today's default name ("Filter components") and no autofocus, unchanged. A caller naming a
+ * genuinely different search surface — e.g. `SourceReferencePicker.tsx`'s catalog-wide picker,
+ * which is not the sidebar's own filter — overrides the label so its own durable name stays
+ * truthful, rather than three different filters all claiming to be "Filter components".
  */
 export function CatalogSearchInput({
   value,
   onChangeText,
   placeholder,
+  accessibilityLabel = 'Filter components',
+  autoFocus = false,
+  inputRef: providedInputRef,
 }: {
   value: string;
   onChangeText: (text: string) => void;
   placeholder: string;
+  accessibilityLabel?: string;
+  autoFocus?: boolean;
+  /** Focus after a surrounding modal has shown, without racing its trigger-focus capture. */
+  inputRef?: RefObject<TextInput | null>;
 }) {
   // Focus draws the catalog focus ring — react-native-web resets the browser's default input focus
   // ring, so the box has to draw its own indicator.
@@ -25,7 +38,8 @@ export function CatalogSearchInput({
   // project's Pressable types (targeting native) don't expose that field, though RNW fires the events.
   const [clearHovered, setClearHovered] = useState(false);
   // Clearing unmounts the clear button that has focus; return focus to the field it cleared.
-  const inputRef = useRef<TextInput>(null);
+  const localInputRef = useRef<TextInput>(null);
+  const inputRef = providedInputRef ?? localInputRef;
   return (
     <View style={[styles.box, focused && styles.boxFocused]}>
       <TextInput
@@ -35,7 +49,8 @@ export function CatalogSearchInput({
         placeholder={placeholder}
         placeholderTextColor={CATALOG_COLOR.textMuted}
         // A durable name — the placeholder alone disappears the moment the user types.
-        accessibilityLabel="Filter components"
+        accessibilityLabel={accessibilityLabel}
+        autoFocus={autoFocus}
         onFocus={() => setFocused(true)}
         onBlur={() => setFocused(false)}
         style={styles.input}