Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
9.4 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file contract/fromComponentDoc.ts
 * @input A component's documentation (.doc.mjs) plus the native additions for it
 * @output A component contract: the portable core, native platform props, and the
 *   web-only props with reasons
 * @position Turns core documentation into the contract the generators consume.
 *   Reads documentation as data at build time; never imports core at run time
 *   (AST-082 FR16)
 */

import {parseDocType} from './parseDocType.js';
import {coreNameProblem} from './rules.js';
import type {
  BaseTarget,
  ComponentContract,
  PropMap,
  PropSpec,
  PropType,
  WebOnlyProp,
} from './types.js';
import type {NativePlatform} from '../platforms.js';

interface DocProp {
  readonly name: string;
  readonly type?: unknown;
  readonly required?: boolean;
  readonly description?: unknown;
}

/**
 * The subset of a ComponentDoc this reader needs. A file that documents
 * several components, such as Stack with HStack and VStack, lists them in
 * `components`.
 */
export interface ComponentDocLike {
  readonly name: string;
  readonly props?: ReadonlyArray<DocProp>;
  readonly components?: ReadonlyArray<{
    readonly name: string;
    readonly props?: ReadonlyArray<DocProp>;
  }>;
}

/**
 * Typed slots (AST-082 FR4) for documented free-form content. `text` is a
 * string in the core contract, as a badge's label or a heading's words;
 * `content` is child Astryx components, as a stack's or a card's children;
 * `icon` is a shared icon name (FR17), as an icon's glyph.
 */
export type SlotKind = 'text' | 'content' | 'icon';

/** What the native package adds to one core component. */
export interface NativeAdditions {
  readonly name: string;
  readonly baseTarget: BaseTarget;
  /**
   * Where core documents the component when it is not `<Name>/<Name>.doc.mjs`:
   * `file` relative to core's `src` without `.doc.mjs`, and `component` when
   * the file documents several components.
   */
  readonly doc?: {readonly file: string; readonly component?: string};
  /** Documented free-form content props, given a typed slot in the core. */
  readonly slots?: Readonly<Record<string, SlotKind>>;
  /**
   * Callbacks whose only documented argument is a DOM event but which name a
   * moment every platform has, such as a button's press. Their core form
   * takes no arguments.
   */
  readonly callbacks?: readonly string[];
  /**
   * Core props whose name a platform toolkit also uses, with the same meaning
   * (AST-082 FR8 forbids only a different meaning), and why: a button's
   * `onClick` is a press in Compose too.
   */
  readonly sameMeaning?: Readonly<Record<string, string>>;
  /**
   * Portable definitions for named types the documentation references. Fields
   * the web type has that are not portable are left out on purpose.
   */
  readonly types?: Readonly<Record<string, PropMap>>;
  /** Documented types renamed to a native definition, e.g. `SelectorOption[]`. */
  readonly typeNames?: Readonly<Record<string, string>>;
  readonly platforms?: Readonly<Partial<Record<NativePlatform, PropMap>>>;
  /**
   * Props whose web type is wider than a portable kind, with the closed set of
   * values every platform supports, each mapped to the one web value it means
   * (AST-082 FR4), such as Button `width`: `content` is the web's `'auto'`
   * and `fill` its `'100%'`. The web's default keeps its meaning. The prop's other
   * web values stay in the web contract.
   */
  readonly projections?: Readonly<
    Record<string, Readonly<Record<string, string>>>
  >;
  /**
   * Portable-typed props that still belong to the web contract, with the
   * reason, such as a web presentation heuristic a native platform replaces.
   */
  readonly webOnly?: Readonly<Record<string, string>>;
  /**
   * Portable core-doc props that only some native platforms carry, with those
   * platforms and the reason (AST-082 FR3): the prop leaves the core and joins
   * each listed platform's contract unchanged, so a platform a ruling covers
   * drops it while the others keep it.
   */
  readonly onlyOn?: Readonly<
    Record<
      string,
      {readonly platforms: readonly NativePlatform[]; readonly reason: string}
    >
  >;
}

/** The documented props of the component the additions name. */
function documentedProps(
  doc: ComponentDocLike,
  additions: NativeAdditions,
): ReadonlyArray<DocProp> {
  const wanted = additions.doc?.component;
  if (wanted == null) {
    return doc.props ?? [];
  }
  const entry = doc.components?.find(component => component.name === wanted);
  if (!entry) {
    throw new Error(
      `${additions.name}: core documentation "${doc.name}" does not document "${wanted}"`,
    );
  }
  return entry.props ?? [];
}

const SLOT_TYPES: Readonly<Record<SlotKind, PropType>> = {
  text: {kind: 'string'},
  content: {kind: 'content'},
  icon: {kind: 'icon'},
};

export function fromComponentDoc(
  doc: ComponentDocLike,
  additions: NativeAdditions,
): ComponentContract {
  const core: Record<string, PropSpec> = {};
  const webOnly: WebOnlyProp[] = [];
  const projections: Record<string, Readonly<Record<string, string>>> = {};
  const types = additions.types ?? {};
  const describe = (prop: DocProp) =>
    typeof prop.description === 'string' ? {doc: prop.description} : {};

  for (const prop of documentedProps(doc, additions)) {
    // `id` and `isHidden` are shared base props on every platform (FR7), so a
    // documented prop of either name is the base prop, not a core prop.
    if (prop.name === 'id' || prop.name === 'isHidden') {
      continue;
    }
    const declaredWebOnly = additions.webOnly?.[prop.name];
    if (declaredWebOnly) {
      webOnly.push({name: prop.name, reason: declaredWebOnly});
      continue;
    }
    if (
      /(?:Xstyle|XStyle|ClassName|Style)$/.test(prop.name) ||
      prop.name === 'xstyle'
    ) {
      webOnly.push({name: prop.name, reason: 'web styling input'});
      continue;
    }
    if (prop.name.startsWith('html') || prop.name.startsWith('aria-')) {
      webOnly.push({name: prop.name, reason: 'HTML attribute'});
      continue;
    }
    const projection = additions.projections?.[prop.name];
    if (projection) {
      const mapping = Object.entries(projection)
        .map(
          ([value, web]) =>
            `\`${value}\` is the web's \`${JSON.stringify(web)}\``,
        )
        .join(', ');
      core[prop.name] = {
        type: {kind: 'enum', values: Object.keys(projection)},
        optional: prop.required !== true,
        doc: `${typeof prop.description === 'string' ? `${prop.description} ` : ''}Native values: ${mapping}.`,
      };
      projections[prop.name] = projection;
      continue;
    }
    const slot = additions.slots?.[prop.name];
    const slotNameProblem =
      slot &&
      coreNameProblem(prop.name, prop.name in (additions.sameMeaning ?? {}));
    if (slotNameProblem) {
      webOnly.push({name: prop.name, reason: slotNameProblem});
      continue;
    }
    if (slot) {
      core[prop.name] = {
        type: SLOT_TYPES[slot],
        optional: prop.required !== true,
        ...describe(prop),
      };
      continue;
    }
    let parsed = parseDocType(String(prop.type ?? ''));
    if (
      !parsed.ok &&
      parsed.eventOnly === true &&
      additions.callbacks?.includes(prop.name)
    ) {
      parsed = {ok: true, type: {kind: 'fn', args: []}};
    }
    if (!parsed.ok) {
      webOnly.push({name: prop.name, reason: parsed.reason});
      continue;
    }
    // A portable type can still carry a name another platform owns.
    const nameProblem = coreNameProblem(
      prop.name,
      prop.name in (additions.sameMeaning ?? {}),
    );
    if (nameProblem) {
      webOnly.push({name: prop.name, reason: nameProblem});
      continue;
    }
    let type = parsed.type;
    const renamed = (name: string) => additions.typeNames?.[name] ?? name;
    if (type.kind === 'named') {
      type = {kind: 'named', name: renamed(type.name)};
    }
    if (type.kind === 'array' && type.of.kind === 'named') {
      type = {kind: 'array', of: {kind: 'named', name: renamed(type.of.name)}};
    }
    if (type.kind === 'named' && !(type.name in types)) {
      webOnly.push({
        name: prop.name,
        reason: `type "${type.name}" has no portable definition yet`,
      });
      continue;
    }
    if (
      type.kind === 'array' &&
      type.of.kind === 'named' &&
      !(type.of.name in types)
    ) {
      webOnly.push({
        name: prop.name,
        reason: `type "${type.of.name}" has no portable definition yet`,
      });
      continue;
    }
    core[prop.name] = {
      type,
      optional: prop.required !== true,
      ...describe(prop),
    };
  }

  const platforms: Partial<Record<NativePlatform, Record<string, PropSpec>>> =
    Object.fromEntries(
      Object.entries(additions.platforms ?? {}).map(([p, props]) => [
        p,
        {...props},
      ]),
    );
  for (const [name, {platforms: only}] of Object.entries(
    additions.onlyOn ?? {},
  )) {
    const spec = core[name];
    if (!spec) {
      throw new Error(
        `${additions.name}: onlyOn names "${name}", which is not a portable core prop`,
      );
    }
    delete core[name];
    for (const platform of only) {
      platforms[platform] = {...platforms[platform], [name]: spec};
    }
  }

  return {
    name: additions.name,
    baseTarget: additions.baseTarget,
    types,
    core,
    platforms,
    webOnly,
    projections,
    sameMeaning: Object.keys(additions.sameMeaning ?? {}).filter(
      name => name in core,
    ),
  };
}