@krapwoo/ds-viewer 0.9.1 → 0.11.0

package/native/catalog/types.ts

@@ -72,6 +72,9 @@ export interface VariantSlot {
    *  it only ever lowers the natural, width-based column count, never raises it. Omit to let the
    *  slot's specimen size and available width decide alone (today's behavior, unchanged). */
   maxColumns?: 1 | 2 | 3 | 4 | 5;
+  /** Names the one property this grid varies (e.g. "Expression", "Shape"). Shown as the grid's
+   *  label, including on family pages, which otherwise hide block labels. */
+  axis?: string;
   items: VariantExample[];
 }
 
@@ -274,6 +277,9 @@ export interface SectionDef<TId extends string = string> {
    *  so the exemption is a visible declaration in the page rather than a silent gap — write an
    *  example instead whenever the reader really does choose the value. */
   internalProps?: Record<string, string>;
+  /** Set when the authored page has `members`: the viewer renders a `FamilyPage` instead of the
+   *  normal single-component layout. See `CatalogPageInput.members` and `FamilyDef`. */
+  family?: FamilyDef;
 }
 
 /** A labeled group of section ids in the sidebar (e.g. "Components" vs "Tokens"). */
@@ -313,6 +319,106 @@ export interface VersionStatus {
   update: UpdateNotice | null;
 }
 
+/** One documented declaration on a family page (spec §5.1): its name, source location, fidelity,
+ *  specimens or reference text, and API. The whole (the page's own `id`) is a member too. */
+export interface CatalogMember {
+  id: string;
+  /** A detected component export. Its generated props go in the disclosure, and its stub page is
+   *  suppressed. Omit for a documentation-only member with no rendered specimen. */
+  component?: string;
+  /** The native source shown in the line below the specimens, `path:line`. */
+  source: string;
+  fidelity: 'replicated' | 'approximated' | 'documentation-only';
+  /** For example "Anatomy", "Native integration", "Helper". Slice D1 removed the below-specimens
+   *  line's own relationship/section-label display entirely (the anatomy box replaced it); kept as
+   *  authored data for your own reference, but not read by the renderer. */
+  relationship: string;
+  /** The member that contains or uses this one. Omitted on the whole and on related roots. */
+  parent?: string;
+  /** Short sentence for members outside the whole (e.g. "Wraps BotAvatarView"). Member names
+   *  inside it become links to that member's address. */
+  related?: string;
+  description: string;
+  variants?: VariantSlot;
+  states?: VariantSlot;
+  comparison?: ComparisonDef;
+  /** Bullets inside the disclosure. */
+  notes?: string[];
+  whenToUse?: string;
+  a11y?: string;
+  /** Swift declaration excerpt, generated by the host app's scanner, shown in the disclosure. */
+  api?: string;
+  /** What this member is built from or composed with — same meaning as `SectionDef.composedOf`,
+   *  shown in the disclosure as one "Uses …" line (`disclosureContent`'s `'uses'` part). */
+  composedOf?: ComposedOfEntry[];
+  notShown?: string;
+  /** Display only, same meaning as `SectionDef.hide` — not a doctor exemption. */
+  hide?: { accessibility?: boolean; props?: boolean };
+  /** Extra names (e.g. retired page ids) that resolve to this member. */
+  aliases?: string[];
+  /** Same meaning as `SectionDef.osComponent` — rendered as the same small badge in the member
+   *  header. */
+  osComponent?: 'full' | 'partial';
+  previewWidths?: PreviewWidths;
+  previewLayout?: 'frames' | 'table';
+  specimenSize?: SpecimenSize;
+  specimenSurface?: SpecimenSurfaceKind;
+  /** Same meaning as `SectionDef.intentionalStaticPreview` — accepted per member, but not yet
+   *  consumed by anything (neither the viewer nor `doctor`'s member-level checks read it). */
+  intentionalStaticPreview?: { reason: string };
+}
+
+/** One section of a family page (spec §5.1): `kind` alone decides full blocks versus the folded
+ *  list card. `inWhole` sections come right after the whole; the others come after them — ordering
+ *  only, numbering follows each member's own `parent` (see `numberFor`); a Related (non-`inWhole`)
+ *  member is never numbered. */
+export interface CatalogMemberSection {
+  label: string;
+  kind: 'blocks' | 'list';
+  inWhole: boolean;
+  members: string[];
+}
+
+/** Slice D1: one row of a family page's anatomy legend — either a `member` of this page (numbered,
+ *  linked to that member's address) or a component `other`wise documented elsewhere (never
+ *  numbered; linked only when the name resolves to a real catalog address). `description` is this
+ *  legend row's own text, independent of the member's own `description`. */
+export type CatalogAnatomyItem = ({ member: string } | { other: string }) & { description: string };
+
+/** One labeled group of anatomy legend rows (e.g. "In this picture", "No area of their own",
+ *  "From other pages") — a group never splits across legend columns (`AnatomyPin`/`FamilyPage`). */
+export interface CatalogAnatomyGroup {
+  label: string;
+  items: CatalogAnatomyItem[];
+}
+
+/** Slice D1 item 1: the anatomy box at the top of a family page — a picture of the whole with
+ *  numbered pins (via `AnatomyPin`, looked up through context so the picture never hardcodes a
+ *  number), and a legend beside it (six items or fewer) or below it in up to three balanced
+ *  columns. Omit for a family page with no anatomy picture. */
+export interface CatalogAnatomy {
+  picture?: React.ReactNode;
+  groups: CatalogAnatomyGroup[];
+}
+
+/** A family page's members with resolved props and paths, the whole, sections, and the computed
+ *  outline — set on `SectionDef.family` by `buildCatalogSections` when a page has `members`. */
+export interface FamilyDef {
+  whole: string;
+  members: Array<CatalogMember & { props?: PropDef[]; path: string }>;
+  sections: CatalogMemberSection[];
+  outline: Map<string, { number: string; level: number }>;
+  notShown?: string;
+  /** Extra names for the page itself (its whole) — e.g. retired page ids. See
+   *  `CatalogPageInput.aliases`. */
+  aliases?: string[];
+  /** Label for the disclosure's API part (`disclosureLabel`). See `CatalogPageInput.apiLabel`.
+   *  Defaults to `'API'` when absent. */
+  apiLabel?: string;
+  /** Slice D1 item 1. See `CatalogPageInput.anatomy`. */
+  anatomy?: CatalogAnatomy;
+}
+
 /** One titled card on a token page (`SectionDef.tokenSections`). */
 export interface TokenSection {
   /** The kind of token this card holds, e.g. "Semantic colours", "Palette", "Body". */

package/package.json

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