@krapwoo/ds-viewer 0.15.0 → 0.16.0

package/README.md

@@ -132,7 +132,7 @@ identified.
 
 `ds-viewer.config.ts` fields: `name`, `logo` (optional — a path to an image asset, shown in the
 sidebar beside the name, or in place of it for a wide wordmark; validated at `sync`/`dev` time
-and bundled into the preview workspace), `components`, `exclude`, `tokens`, `pages`, `groupOrder`, `starterKit` (new-project only —
+and bundled into the preview workspace), `components`, `exclude`, `tokens`, `pages`, `groupOrder`, `patternGroups`, `starterKit` (new-project only —
 records the kit's version), `updateCheck`, `doctor` — see `config/index.ts`'s `DsViewerConfig` for
 each field's exact meaning. Write a page with `defineCatalogPage()` from `@krapwoo/ds-viewer` (same
 shape as a `SectionDef`, minus `id`/`path`/`props`, plus `component`, `group`, and `propNotes`).
@@ -495,6 +495,13 @@ path. For anything beyond a single list of tokens, use the token-page layouts be
   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.
+- **Parts and empty pages.** `doctor` warns about a page that is only a built-in part of one other
+  page (`part-own-page`) and about a page that shows nothing (`nothing-to-show`); see the rule list
+  under `doctor`. To keep such a page on purpose, set `standalone: '<why>'`, for example
+  `standalone: 'Not a part of GitFileCard; it draws its own counts.'`. The reason must be non-blank
+  and is only a note in the source — the viewer ignores it. Family and group pages, token pages and
+  `navigation: 'reference'` pages are never checked. Both checks count `composedOf` written on a
+  family or group member as well as on a page.
 - **Coverage only counts the component's own options.** `doctor`'s `option-not-covered` checks
   string-literal unions declared in the component's own folder or a token folder. A union
   declared in another component's folder, such as a shared `IconName`, is that component's
@@ -905,6 +912,23 @@ Button
     non-`inWhole` section, naming every one of them so you can act without opening the file. Give
     each its own catalog page and name it in the family's `relatedPages` list instead; the section
     keeps working until you do.
+  - `part-own-page` — a standalone page for a component that exactly one other page declares in
+    `composedOf` as `relationship: 'built-in'`, and that page doesn't list it as a member. Fold it
+    into that page's family, or record why it isn't part of it with `standalone`. A component built
+    into two or more pages is exempt, and `'slot'`/`'related'` entries never count. Pages in a pattern
+    group (example screens built from components) never count as the whole: by default the group
+    named `Patterns`; set `patternGroups` in `ds-viewer.config.ts` to name your own (e.g.
+    `patternGroups: ['Screens']`).
+  - `nothing-to-show` — a plain page with no variants, states, `render` or comparison, and no
+    members or token content (`previewWidths` alone doesn't count; it only sizes `render`). The
+    message names the pages that list it in `composedOf` — on the page or on one of its members —
+    or says only pattern pages use it, or that nothing does. List it as a documentation-only part
+    of a page that uses it, set `navigation: 'reference'`, or add a `standalone` reason. A page
+    whose specimens can't be read literally is never reported. A component page with no specimens
+    usually also gets `component-no-examples` (unless the component is documented elsewhere, on
+    another page or as a family member); the two say different things (no examples vs. no reason to
+    be its own page) and clear together once it has a specimen.
+  - `standalone-reason-empty` — `standalone` is blank, so it records no reason and opts nothing out.
 
   The catalog also warns at render time when a page under-declares the width its examples need.
   A `PhoneFrame` given a cell narrower than the 375px device scales the whole phone down, and its

package/config/index.ts

@@ -16,6 +16,9 @@ export interface DsViewerConfig {
   pages?: string[];
   /** Sidebar group display order; groups not listed here follow alphabetically. */
   groupOrder?: string[];
+  /** Sidebar groups whose pages are patterns: example screens built from components. `doctor`
+   *  never treats a pattern page as the whole a component is a part of. @default ['Patterns'] */
+  patternGroups?: string[];
   /** Starter-kit projects only. `root` is the folder `init --new` copied the kit into (default
    *  `src/ds`); absent on a config written before 0.4, in which case `cli/kitRoot.ts` infers it
    *  from the first `components` glob instead. */

package/dist/cli/config.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { defineConfig } from "../config/index.js";
 const KNOWN_FIELDS = new Set([
-    'name', 'logo', 'components', 'exclude', 'tokens', 'pages', 'groupOrder', 'starterKit', 'updateCheck', 'doctor',
+    'name', 'logo', 'components', 'exclude', 'tokens', 'pages', 'groupOrder', 'patternGroups', 'starterKit', 'updateCheck', 'doctor',
 ]);
 /**
  * Loads `ds-viewer.config.ts` with a bundled TypeScript loader. This is a guard rail, not a
@@ -41,6 +41,13 @@ export function loadConfig(configPath) {
         if (!KNOWN_FIELDS.has(key))
             warnings.push(`Unknown config field "${key}" is ignored.`);
     }
+    let patternGroups;
+    if (raw.patternGroups !== undefined) {
+        if (Array.isArray(raw.patternGroups) && raw.patternGroups.every((name) => typeof name === 'string'))
+            patternGroups = raw.patternGroups;
+        else
+            warnings.push('"patternGroups" must be an array of group names; using the default [\'Patterns\'].');
+    }
     const config = {
         name: raw.name ?? '',
         logo: raw.logo,
@@ -49,6 +56,7 @@ export function loadConfig(configPath) {
         tokens: raw.tokens ?? [],
         pages: raw.pages ?? [],
         groupOrder: raw.groupOrder ?? [],
+        patternGroups,
         starterKit: raw.starterKit,
         updateCheck: raw.updateCheck ?? true,
         doctor: raw.doctor ?? { strict: false },

package/dist/cli/doctor.js

@@ -530,6 +530,146 @@ function checkMissingComposition(pages, components) {
     }
     return issues;
 }
+/** #66: a page is a family or group (it has `members`) — presence, so a page whose `members` could
+ *  not be read is still never treated as a plain page. */
+function hasMembers(page) {
+    return page.hasMembers === true || Boolean(page.members && page.members.length > 0);
+}
+/** #66: a token page — a `tokenDefinition`, a token gallery, or token sections, by presence. */
+function isTokenPage(page) {
+    return page.hasTokenDefinition === true || page.tokenDefinition !== undefined || page.tokenGallery === true
+        || page.hasExplicitTokenGallery === true || page.hasExplicitTokenSections === true || Boolean(page.tokenSectionTitles?.length);
+}
+/** #66: a non-blank `standalone` reason opts a page out of `part-own-page` and `nothing-to-show`. */
+function hasStandaloneReason(page) {
+    return page.standalone !== undefined && page.standalone.trim() !== '';
+}
+/** #66: the pages the two structure rules consider — readable, plain (no members, not a token page),
+ *  browse-listed, and without a recorded `standalone` reason. */
+function isStructureCandidate(page) {
+    return page.checkable && !hasMembers(page) && !isTokenPage(page) && page.navigation !== 'reference' && !hasStandaloneReason(page);
+}
+/** #66: the default `patternGroups` — the starter kit's own group for example screens. */
+export const DEFAULT_PATTERN_GROUPS = ['Patterns'];
+/** #66: whether a page sits in a pattern group (case-insensitive). A pattern page uses components; it
+ *  is never the whole they are parts of. */
+function isPatternPage(page, patternGroups) {
+    const group = page.group?.trim().toLowerCase();
+    return group !== undefined && patternGroups.some((name) => name.trim().toLowerCase() === group);
+}
+/** #66 `standalone-reason-empty`: a `standalone` that is blank or whitespace records no reason, so it
+ *  is not an opt-out. */
+function checkStandaloneReason(pages) {
+    return pages
+        .filter((page) => page.standalone !== undefined && page.standalone.trim() === '')
+        .map((page) => issue({
+        id: 'standalone-reason-empty', severity: 'warning', ...pageRef(page),
+        message: '`standalone` is empty, so it does not opt this page out of the structure checks.',
+        fix: "Write the reason, e.g. standalone: 'Not a part of GitFileCard; it draws its own counts.', or remove the field.",
+    }));
+}
+/** #66: every page that uses one of `names`, excluding `self`, deduplicated by host page (a page
+ *  counts once however many of its entries name the component). A built-in entry anywhere on the
+ *  host wins over a non-built-in one. */
+function usesOf(pages, self, names) {
+    const byHost = new Map();
+    for (const host of pages) {
+        if (host === self)
+            continue;
+        const entries = [...(host.composedOf ?? []), ...(host.members ?? []).flatMap((member) => member.composedOf ?? [])];
+        for (const entry of entries) {
+            if (!names.has(entry.component))
+                continue;
+            const known = byHost.get(host);
+            if (!known || (known.relationship !== 'built-in' && entry.relationship === 'built-in'))
+                byHost.set(host, { host, relationship: entry.relationship });
+        }
+    }
+    return [...byHost.values()];
+}
+/** #66: the names a page answers to — its id and its component. */
+function pageNames(page) {
+    return new Set([resolvePageId(page, page.file), ...(page.component ? [page.component] : [])]);
+}
+/** #66: whether some other page has composition this reader couldn't read — a page-level or
+ *  member-level `composedOf`, or a `members` list that wasn't read at all — so "only" and "nothing
+ *  uses it" can't be claimed outright. */
+function hasUnreadableComposition(pages, self) {
+    return pages.some((other) => other !== self && ((other.hasComposedOf === true && other.composedOf === undefined)
+        || (other.hasMembers === true && other.members === undefined)
+        || Boolean(other.members?.some((member) => member.hasComposedOf === true && member.composedOf === undefined))));
+}
+const pageList = (pages) => [...new Set(pages.map((p) => `\`${resolvePageId(p, p.file)}\``))].join(', ');
+/** #66 `part-own-page`: a candidate page whose component is declared `{ relationship: 'built-in' }`
+ *  (at page or member level) by exactly one other non-pattern page, which doesn't already list it
+ *  as a member (by member id, component or alias). Two or more users can't give it one owner, so it
+ *  is exempt; `slot`/`related`/missing/non-literal relationships never count. Reports; never infers
+ *  an owner or a relationship. */
+function checkPartOwnPage(pages, patternGroups) {
+    const issues = [];
+    for (const page of pages) {
+        if (!isStructureCandidate(page))
+            continue;
+        const names = pageNames(page);
+        const owners = usesOf(pages, page, names)
+            .filter((use) => use.relationship === 'built-in' && !isPatternPage(use.host, patternGroups))
+            .map((use) => use.host);
+        if (owners.length !== 1)
+            continue;
+        const owner = owners[0];
+        if (owner.members?.some((member) => names.has(member.id) || (member.component !== undefined && names.has(member.component))
+            || member.aliases?.some((alias) => names.has(alias))))
+            continue;
+        const ownerId = resolvePageId(owner, owner.file);
+        const id = resolvePageId(page, page.file);
+        const caveat = hasUnreadableComposition(pages, page) ? ' (Some pages\' `composedOf` could not be read, so another user may exist.)' : '';
+        issues.push(issue({
+            id: 'part-own-page', severity: 'warning', ...pageRef(page),
+            message: `\`${id}\` is a built-in part of \`${ownerId}\` only, but has its own page.${caveat}`,
+            fix: `List it as a part in ${ownerId}'s family (\`members\`/\`sections\`), or set \`standalone: '<reason>'\` if it is not really part of ${ownerId}.`,
+        }));
+    }
+    return issues;
+}
+/** #66 `nothing-to-show`: a candidate page with no variants, states, comparison or `render`. A page
+ *  this reader could not fully read is never a candidate (`checkable`), so "nothing" is only claimed
+ *  about a page that was read in full. `previewWidths` alone is not content: it only sizes `render`. */
+function checkNothingToShow(pages, patternGroups) {
+    const issues = [];
+    for (const page of pages) {
+        if (!isStructureCandidate(page))
+            continue;
+        const hasSpecimens = Boolean(page.comparison) || Boolean(page.variantsItems?.length) || Boolean(page.statesItems?.length) || page.hasRender === true;
+        if (hasSpecimens)
+            continue;
+        const id = resolvePageId(page, page.file);
+        const hosts = usesOf(pages, page, pageNames(page)).map((use) => use.host);
+        const users = hosts.filter((host) => !isPatternPage(host, patternGroups));
+        const patternUsers = hosts.filter((host) => isPatternPage(host, patternGroups));
+        const unreadable = hasUnreadableComposition(pages, page);
+        const base = { id: 'nothing-to-show', severity: 'warning', ...pageRef(page) };
+        const otherFix = "Add a specimen, set `navigation: 'reference'`, or `standalone: '<reason>'`.";
+        if (users.length > 0) {
+            const alsoPatterns = patternUsers.length > 0 ? ` Pattern pages also use it (${pageList(patternUsers)}).` : '';
+            issues.push(issue({ ...base,
+                message: `\`${id}\` shows no specimens. It is used by ${pageList(users)}.${alsoPatterns}`,
+                fix: "List it on that page as a documentation-only part, or set `navigation: 'reference'` to keep it reachable through Source reference search without a browse entry, or `standalone: '<reason>'`.",
+            }));
+        }
+        else if (patternUsers.length > 0) {
+            issues.push(issue({ ...base, message: `\`${id}\` shows no specimens. Only pattern pages use it (${pageList(patternUsers)}).`, fix: otherFix }));
+        }
+        else {
+            issues.push(issue({ ...base,
+                message: unreadable
+                    ? `\`${id}\` shows no specimens, and no page whose \`composedOf\` doctor could read uses it.`
+                    : `\`${id}\` shows no specimens and no other page uses it.`,
+                fix: otherFix,
+            }));
+        }
+    }
+    return issues;
+}
 /** The viewer exports that frame an example as a phone (or another bounded document), so an
  *  overlay that portals to the document body opens inside it instead of over the catalog. */
 const DEVICE_FRAME_EXPORTS = ['PhoneFrame', 'OverlayDemo', 'PhoneScreen', 'BoundedOverlayViewport'];
@@ -997,7 +1137,8 @@ function checkTokenDefinitionAliases(pages) {
     return issues;
 }
 /** Every page-scoped issue, from every rule above. */
-export function collectIssues(pages, components) {
+export function collectIssues(pages, components, options = {}) {
+    const patternGroups = options.patternGroups ?? DEFAULT_PATTERN_GROUPS;
     return [
         ...checkParseErrors(pages),
         ...checkNotCheckable(pages),
@@ -1009,6 +1150,9 @@ export function collectIssues(pages, components) {
         ...checkDegenerateGridAxis(pages),
         ...checkComponentPages(pages, components),
         ...checkMissingComposition(pages, components),
+        ...checkStandaloneReason(pages),
+        ...checkPartOwnPage(pages, patternGroups),
+        ...checkNothingToShow(pages, patternGroups),
         ...checkMissingWorkingPreview(pages, components),
         ...checkPreviewOnlyPages(pages),
         ...checkFamilyMembers(pages, components),
@@ -1155,7 +1299,7 @@ export function runDoctor(config) {
         ? { '*': [path.join(config.projectRoot, 'node_modules', '@types', '*'), path.join(config.projectRoot, 'node_modules', '*')] }
         : undefined;
     let issues = [
-        ...collectIssues(pages, components),
+        ...collectIssues(pages, components, { patternGroups: config.patternGroups }),
         ...checkPageTypeErrors(pages, { fallbackPaths, hostRoot: config.projectRoot }),
         ...checkOverlaysFramed(pages, components, config.projectRoot),
         ...collectGlobalIssues({ syncWarnings: syncResult.warnings, tokenFileCount }),

package/dist/cli/staticPage.js

@@ -255,6 +255,9 @@ function readStaticPage(file) {
             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) {
@@ -344,6 +347,7 @@ function readFamilyMembers(node, consts, gridNames, sourceFile) {
             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),
@@ -383,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) {
@@ -400,7 +404,8 @@ 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;
 }

package/native/catalog/pageApi.ts

@@ -24,6 +24,9 @@ export interface CatalogPageInput<TId extends string = string> {
   /** Page-level notes, shown as a "Notes" entry in the page's Quick reference (the page-level
    *  counterpart of a family member's `notes`). */
   notes?: string[];
+  /** Why this page stands on its own. Opts it out of `doctor`'s `part-own-page` and
+   *  `nothing-to-show` checks and records the decision in source; the viewer does not render it. */
+  standalone?: string;
   variants?: VariantSlot;
   states?: VariantSlot;
   render?: () => React.ReactNode;

package/package.json

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

package/starter-kit/components/AnimatedChevron/AnimatedChevron.catalog.tsx

@@ -6,6 +6,7 @@ import { DS_SEMANTIC } from '../../tokens';
 export default defineCatalogPage({
   component: 'AnimatedChevron',
   group: 'Components',
+  standalone: 'A reusable kit component in its own right; Banner is just the only kit component that uses it.',
   whenToUse: 'An expand/collapse affordance that should animate its own state change — it flips vertically in place, so it never points sideways mid-transition. Where a chevron never changes state, a plain icon is enough.',
   description: 'A chevron that morphs between down (collapsed) and up (expanded) — flipping vertically in place instead of rotating through a sideways-pointing angle, and instead of swapping icons. The morph Banner\'s own collapsible header uses for its disclosure indicator. Not commonly used on its own; exported for building a custom disclosure/accordion toggle.',
   a11y: 'Purely decorative — no accessibility role of its own. Wrap it in an accessible parent (the way Banner\'s own header Pressable does) if the toggle needs to be announced.',

package/starter-kit/components/Avatar/Avatar.catalog.tsx

@@ -32,6 +32,7 @@ const AVATAR_COMPARISON = grid(
 export default defineCatalogPage({
   component: 'Avatar',
   group: 'Components',
+  standalone: 'A reusable kit component in its own right; EmptyState is just the only kit component that uses it.',
   whenToUse: 'A person or place\'s identity in a circle. Pass whatever you have: image, icon, or initials are tried in that order, so a missing image degrades to initials without leaving a gap.',
   specimenSize: 'compact',
   comparison: AVATAR_COMPARISON,

package/starter-kit/components/BottomSheet/BottomSheet.catalog.tsx

@@ -65,6 +65,7 @@ const dock = (close: () => void) => (
 export default defineCatalogPage({
   component: 'BottomSheet',
   group: 'Components',
+  standalone: 'A reusable kit component in its own right; Dropdown is just the only kit component that uses it.',
   // Every example is a phone. At the default size two blocks share the row and each cell falls to
   // 270px, which squeezes the frame until the sheet's own text is barely readable — 'wide' keeps a
   // 402px minimum, the width the sheet is actually used at.

package/starter-kit/components/ButtonGroup/ButtonGroup.catalog.tsx

@@ -6,6 +6,7 @@ import { Button } from '../Button';
 export default defineCatalogPage({
   component: 'ButtonGroup',
   group: 'Components',
+  standalone: 'A reusable kit component in its own right; EmptyState is just the only kit component that uses it.',
   whenToUse: 'Two or three Buttons that should read as one family — horizontal for a trailing-aligned pair (a dialog\'s Cancel and Confirm), vertical for up to three stretched full width. Keep one variant tier and one size across the group. For a screen\'s bottom action area, use Dock.',
   composedOf: [
     { component: 'Button', role: "Its children: up to two Buttons side by side, or three stacked.", relationship: 'slot' },

package/starter-kit/components/Divider/Divider.catalog.tsx

@@ -12,6 +12,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'Divider',
   group: 'Components',
+  standalone: 'A reusable kit component in its own right; List is just the only kit component that uses it.',
   whenToUse: 'A single hairline between two pieces of content you are laying out yourself. List already puts one between each pair of its rows, so adding your own there would double them.',
   specimenSize: 'regular',
   description: 'A 1px hairline separator at the divider token colour.',

package/starter-kit/components/Pill/Pill.catalog.tsx

@@ -41,6 +41,7 @@ const PILL_COMPARISON = grid(
 export default defineCatalogPage({
   component: 'Pill',
   group: 'Components',
+  standalone: 'A reusable kit component in its own right; PillRow is just the only kit component that uses it.',
   composedOf: [
     { component: 'Loading', role: "The spinner shown instead of the label and icon while loading is true.", relationship: 'built-in' },
   ],

package/starter-kit/components/TopNav/TopNav.catalog.tsx

@@ -12,6 +12,7 @@ const styles = StyleSheet.create({
 export default defineCatalogPage({
   component: 'TopNav',
   group: 'Components',
+  standalone: 'A reusable kit component in its own right; Dropdown is just the only kit component that uses it.',
   whenToUse: 'A screen\'s top bar, and BottomSheet\'s header slot. Its leading and trailing slots reserve their width even when empty, so the title stays centred whether one, both, or neither side has content. For actions at the bottom of a screen, use Dock.',
   composedOf: [
     { component: 'Button', role: "The leading and trailing slots, typically small icon Buttons (back, close, an action).", relationship: 'slot' },