Skip to content

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

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

import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import {fileURLToPath} from 'node:url';
import ts from 'typescript';
import {describe, expect, it} from 'vitest';
import {loadCoreDoc} from '../../scripts/core-docs.mjs';
import {
  buildContracts,
  checkContract,
  generateSwift,
  generateTypeScript,
} from './index.js';
import type {ComponentContract} from './types.js';
import {BUILTIN_ICON_NAMES} from '../icons/defaults.js';

const PACKAGE_ROOT = path.resolve(
  path.dirname(fileURLToPath(import.meta.url)),
  '../..',
);
const APPLE_GENERATED = path.join(
  PACKAGE_ROOT,
  'apple/Sources/AstryxNative/Generated',
);

describe('native contracts', () => {
  it('splits core Selector documentation into a portable core and a web part', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const selector = contracts.find(contract => contract.name === 'Selector');
    expect(selector).toBeDefined();
    expect(Object.keys(selector!.core)).toEqual(
      expect.arrayContaining([
        'label',
        'options',
        'value',
        'onChange',
        'isDisabled',
        'status',
      ]),
    );
    const web = new Map(
      selector!.webOnly.map(prop => [prop.name, prop.reason]),
    );
    expect(web.get('renderOption')).toContain('render function');
    expect(web.get('emptyText')).toContain('typed slot');
    expect(web.get('onClick')).toContain('DOM event');
    expect(web.get('presentation')).toContain(
      'native platforms use their own control',
    );
    expect(selector!.core).not.toHaveProperty('controlXstyle');
  });

  it('moves a prop only some native platforms carry out of the core and onto those platforms', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const switchContract = contracts.find(
      contract => contract.name === 'Switch',
    )!;
    for (const name of ['labelPosition', 'labelSpacing']) {
      expect(switchContract.core).not.toHaveProperty(name);
      expect(switchContract.platforms.android).toHaveProperty(name);
      expect(switchContract.platforms.windows).toHaveProperty(name);
      expect(switchContract.platforms.ios ?? {}).not.toHaveProperty(name);
      expect(switchContract.platforms.macos ?? {}).not.toHaveProperty(name);
    }
  });

  it('keeps value callbacks, typed text slots, and number sets in the core', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const byName = new Map(
      contracts.map(contract => [contract.name, contract]),
    );
    expect(byName.get('Switch')!.core.onChange?.type).toEqual({
      kind: 'fn',
      args: [{kind: 'boolean'}],
    });
    expect(byName.get('TextInput')!.core.onChange?.type).toEqual({
      kind: 'fn',
      args: [{kind: 'string'}],
    });
    expect(byName.get('Button')!.core.onClick?.type).toEqual({
      kind: 'fn',
      args: [],
    });
    // AST-082 FR4: Button `width` projects the web's size value to the two
    // values every platform supports; other widths stay on the web.
    expect(byName.get('Button')!.core.width?.type).toEqual({
      kind: 'enum',
      values: ['content', 'fill'],
    });
    expect(byName.get('Button')!.projections?.width).toEqual({
      content: 'auto',
      fill: '100%',
    });
    expect(byName.get('Heading')!.core.children?.type).toEqual({
      kind: 'string',
    });
    expect(byName.get('Heading')!.core.level?.type).toEqual({
      kind: 'numberEnum',
      values: [1, 2, 3, 4, 5, 6],
    });
    expect(byName.get('Text')!.core).not.toHaveProperty('id');
    expect(byName.get('Badge')!.core.label).toMatchObject({
      type: {kind: 'string'},
      optional: false,
    });
    expect(byName.get('Badge')!.webOnly.map(prop => prop.name)).toContain(
      'icon',
    );
  });

  it('gives Icon a typed icon slot drawn from the shared icon names', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const icon = contracts.find(contract => contract.name === 'Icon');
    expect(icon).toBeDefined();
    expect(icon!.core.icon).toMatchObject({type: {kind: 'icon'}});
    expect(icon!.core.icon.optional).toBe(false);
    expect(Object.keys(icon!.core)).toEqual(['icon', 'color', 'size', 'label']);
    // `variant` names come from core's augmentable `IconVariantMap`, which has
    // no portable definition yet, so the prop stays on the web.
    expect(icon!.webOnly).toEqual([
      {
        name: 'variant',
        reason: 'type "IconVariant" has no portable definition yet',
      },
      {name: 'xstyle', reason: 'web styling input'},
      {
        name: 'className',
        reason: '"className" already means something else in web',
      },
      {name: 'style', reason: 'web styling input'},
      {name: 'ref', reason: 'web element reference'},
    ]);

    const swift = generateSwift(contracts);
    expect(swift['Icon.swift']).toContain('public var icon: IconName');
    const iconName = swift['IconName.swift'];
    for (const name of BUILTIN_ICON_NAMES) {
      expect(iconName).toContain(
        `public static let ${name}: IconName = "${name}"`,
      );
    }
    expect(iconName).toContain('ExpressibleByStringLiteral');

    const types = generateTypeScript(contracts);
    expect(types['core.d.ts']).toContain(
      "export type IconName = 'close' | 'chevronDown'",
    );
    expect(types['core.d.ts']).toContain('icon: IconName;');
  });

  it('gives Icon its semantic colors, and leaves the palette colors on the web', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const icon = contracts.find(contract => contract.name === 'Icon');
    const semantic = [
      'primary',
      'secondary',
      'tertiary',
      'disabled',
      'accent',
      'info',
      'success',
      'error',
      'warning',
      'inherit',
    ];
    expect(icon!.core.color.type).toEqual({kind: 'enum', values: semantic});
    expect(Object.entries(icon!.projections?.color ?? {})).toEqual(
      semantic.map(color => [color, color]),
    );
    expect(generateSwift(contracts)['Icon.swift']).not.toContain('case blue');
  });

  it('gives Avatar its named sizes, a press, and a link, and leaves pixel sizes on the web', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const avatar = contracts.find(contract => contract.name === 'Avatar');
    expect(avatar).toBeDefined();
    expect(avatar!.core.size.type).toEqual({
      kind: 'enum',
      values: ['xsm', 'sm', 'md', 'lg', 'xl'],
    });
    expect(Object.entries(avatar!.projections?.size ?? {})).toEqual(
      ['xsm', 'sm', 'md', 'lg', 'xl'].map(size => [size, size]),
    );
    expect(Object.keys(avatar!.core)).toEqual(
      expect.arrayContaining([
        'src',
        'fallbackSrc',
        'name',
        'alt',
        'shape',
        'href',
        'onClick',
      ]),
    );
    // `string | boolean`: words, or on (the name) and off.
    expect(avatar!.core.tooltip?.type).toEqual({kind: 'textOrBoolean'});
    expect(avatar!.webOnly.map(prop => prop.name)).toEqual(
      expect.arrayContaining(['target', 'rel', 'as']),
    );
  });

  it('gives Avatar a status slot and AvatarStatusDot its variants and label', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const avatar = contracts.find(contract => contract.name === 'Avatar');
    expect(avatar!.core.status?.type).toEqual({kind: 'content'});
    const dot = contracts.find(contract => contract.name === 'AvatarStatusDot');
    expect(dot).toBeDefined();
    expect(dot!.core.variant?.type).toEqual({
      kind: 'enum',
      values: ['success', 'neutral', 'error'],
    });
    expect(dot!.core.label?.type).toEqual({kind: 'string'});
    expect(dot!.webOnly.map(prop => prop.name)).toContain('icon');
  });

  it('gives Thumbnail its image, names, states, a press, and a remove action', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const thumbnail = contracts.find(contract => contract.name === 'Thumbnail');
    expect(thumbnail).toBeDefined();
    expect(Object.keys(thumbnail!.core)).toEqual([
      'src',
      'alt',
      'label',
      'onRemove',
      'onClick',
      'isLoading',
      'isDisabled',
      'showRemoveOn',
    ]);
    expect(thumbnail!.core.onRemove?.type).toEqual({kind: 'fn', args: []});
    expect(thumbnail!.webOnly.map(prop => prop.name)).toEqual(
      expect.arrayContaining(['xstyle', 'className', 'style', 'data-testid']),
    );
  });

  it('gives Item typed text and content slots, a press, and a link, and leaves swipes on the web', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const item = contracts.find(contract => contract.name === 'Item');
    expect(item).toBeDefined();
    expect(item!.core.label).toMatchObject({
      type: {kind: 'string'},
      optional: false,
    });
    expect(item!.core.description?.type).toEqual({kind: 'string'});
    for (const slot of ['marker', 'startContent', 'endContent']) {
      expect(item!.core[slot]?.type).toEqual({kind: 'content'});
    }
    expect(Object.keys(item!.core)).toEqual(
      expect.arrayContaining([
        'align',
        'density',
        'labelLines',
        'descriptionLines',
        'layout',
        'onClick',
        'href',
        'isHighlighted',
        'isSelected',
        'isDisabled',
      ]),
    );
    expect(item!.webOnly.map(prop => prop.name)).toEqual(
      expect.arrayContaining([
        'swipeActions',
        'swipeBehavior',
        'target',
        'rel',
        'data-testid',
        'as',
        'interactiveRef',
      ]),
    );
  });

  it('gives ListItem the row contract without density or markers, which come from its list', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const row = contracts.find(contract => contract.name === 'ListItem');
    expect(row).toBeDefined();
    expect(row!.core.label).toMatchObject({
      type: {kind: 'string'},
      optional: false,
    });
    expect(row!.core.startContent?.type).toEqual({kind: 'content'});
    expect(Object.keys(row!.core)).not.toContain('density');
    expect(row!.webOnly.map(prop => prop.name)).toEqual(
      expect.arrayContaining([
        'swipeActions',
        'swipeBehavior',
        'target',
        'rel',
        'interactiveRef',
      ]),
    );
  });

  it('reports naming and portability errors', () => {
    const bad: ComponentContract = {
      name: 'Bad',
      baseTarget: 'root',
      types: {},
      core: {
        as: {type: {kind: 'string'}},
        style: {type: {kind: 'string'}},
        item: {type: {kind: 'named', name: 'Missing'}},
      },
      platforms: {
        ios: {item: {type: {kind: 'string'}}, var: {type: {kind: 'boolean'}}},
      },
      webOnly: [],
    };
    const rules = checkContract(bad).map(issue => issue.rule);
    expect(rules).toEqual(
      expect.arrayContaining([
        'name-keyword',
        'name-toolkit',
        'platform-shadows-core',
        'unknown-type',
      ]),
    );
  });

  it('keeps the committed Swift binding in sync with the contracts', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    for (const [name, contents] of Object.entries(generateSwift(contracts))) {
      const committed = fs.readFileSync(
        path.join(APPLE_GENERATED, name),
        'utf8',
      );
      expect(
        committed,
        `${name} is stale; run pnpm -F @astryxdesign/native generate:apple`,
      ).toBe(contents);
    }
  });

  it('exposes each platform only its own props through type-resolution conditions', async () => {
    const {contracts} = await buildContracts(loadCoreDoc);
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-native-types-'));
    const pkg = path.join(dir, 'node_modules/@astryxdesign/native');
    fs.mkdirSync(path.join(pkg, 'types'), {recursive: true});
    for (const [name, contents] of Object.entries(
      generateTypeScript(contracts),
    )) {
      fs.writeFileSync(path.join(pkg, 'types', name), contents);
    }
    const manifest = JSON.parse(
      fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8'),
    );
    const exportsMap = JSON.stringify(
      manifest.exports['./components'],
    ).replaceAll('./dist/types/', './types/');
    fs.writeFileSync(
      path.join(pkg, 'package.json'),
      JSON.stringify({
        name: '@astryxdesign/native',
        type: 'module',
        exports: {'./components': JSON.parse(exportsMap)},
      }),
    );
    const usage = (menuStyle: string) =>
      "import type {SelectorProps} from '@astryxdesign/native/components';\n" +
      `export const props: SelectorProps = {label: 'Shipping', options: [], menuStyle: '${menuStyle}'};\n`;

    const errorsFor = (condition: string | null, source: string) => {
      const file = path.join(dir, `${condition ?? 'none'}.ts`);
      fs.writeFileSync(file, source);
      const program = ts.createProgram([file], {
        strict: true,
        noEmit: true,
        module: ts.ModuleKind.ESNext,
        moduleResolution: ts.ModuleResolutionKind.Bundler,
        customConditions: condition ? [condition] : [],
        types: [],
      });
      return ts
        .getPreEmitDiagnostics(program)
        .map(d => ts.flattenDiagnosticMessageText(d.messageText, '\n'));
    };

    expect(errorsFor('ios', usage('pullDown'))).toEqual([]);
    expect(errorsFor('android', usage('bottomSheet'))).toEqual([]);
    expect(errorsFor('android', usage('pullDown')).join('\n')).toContain(
      'pullDown',
    );
    expect(errorsFor('shared', usage('pullDown')).join('\n')).toContain(
      'menuStyle',
    );
    expect(errorsFor(null, usage('pullDown')).join('\n')).toContain(
      'menuStyle',
    );

    const wire = (node: string, action: string) =>
      "import type {AstryxAction, AstryxNode} from '@astryxdesign/native/components';\n" +
      `export const node: AstryxNode = ${node};\n` +
      `export const action: AstryxAction = ${action};\n`;
    const tree =
      "{component: 'VStack', key: 'root', props: {gap: 2, children: [" +
      "{component: 'Switch', key: 'wifi', props: {label: 'Wi-Fi', value: true}, events: ['onChange']}," +
      "{component: 'Selector', key: 'ship', props: {label: 'Shipping', options: [], menuStyle: 'pullDown'}}]}}";
    const toggled =
      "{key: 'wifi', component: 'Switch', event: 'onChange', args: [false]}";
    expect(errorsFor('ios', wire(tree, toggled))).toEqual([]);
    expect(errorsFor('android', wire(tree, toggled)).join('\n')).toContain(
      'pullDown',
    );
    expect(
      errorsFor(
        'ios',
        wire(
          tree,
          "{key: 'wifi', component: 'Switch', event: 'onChange', args: ['off']}",
        ),
      ).length,
    ).toBeGreaterThan(0);
  });
});