@astryxdesign/native 0.0.0-bootstrap.1 → 0.7.4-canary.720bb10

package/src/contract/generateTypeScript.ts

@@ -0,0 +1,115 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract/generateTypeScript.ts
+ * @input Component contracts
+ * @output Declaration files: core.d.ts, one per native platform, and shared.d.ts
+ * @position Produces the platform-scoped types (AST-082 FR5, FR6). The package
+ *   exports map selects one file per type-resolution condition
+ */
+
+import {NATIVE_PLATFORMS, type NativePlatform} from '../platforms.js';
+import type {ComponentContract, PropMap, PropType} from './types.js';
+
+const HEADER = '// Generated by @astryxdesign/native. Do not edit.\n';
+
+function tsType(type: PropType): string {
+  switch (type.kind) {
+    case 'string':
+    case 'number':
+    case 'boolean':
+      return type.kind;
+    case 'enum':
+      return type.values.map(value => `'${value}'`).join(' | ');
+    case 'array': {
+      const inner = tsType(type.of);
+      return `ReadonlyArray<${inner}>`;
+    }
+    case 'record':
+      return `{${members(type.fields, ' ')}}`;
+    case 'fn':
+      return `(${type.args.map((arg, i) => `arg${i}: ${tsType(arg)}`).join(', ')}) => void`;
+    case 'named':
+      return type.name;
+  }
+}
+
+function key(name: string): string {
+  return /^[A-Za-z_$][\w$]*$/.test(name) ? name : `'${name}'`;
+}
+
+function members(props: PropMap, separator = '\n  '): string {
+  return Object.entries(props)
+    .map(
+      ([name, spec]) =>
+        `${key(name)}${spec.optional ? '?' : ''}: ${tsType(spec.type)};`,
+    )
+    .join(separator);
+}
+
+function coreFile(contracts: readonly ComponentContract[]): string {
+  const types = new Map<string, PropMap>();
+  for (const contract of contracts) {
+    for (const [name, fields] of Object.entries(contract.types)) {
+      types.set(name, fields);
+    }
+  }
+  const typeDecls = [...types].map(
+    ([name, fields]) => `export interface ${name} {\n  ${members(fields)}\n}`,
+  );
+  const props = contracts.map(
+    contract =>
+      `/** Core contract. Base props attach to the ${contract.baseTarget}. */\n` +
+      `export interface ${contract.name}CoreProps extends AstryxSharedBaseProps {\n  ${members(contract.core)}\n}`,
+  );
+  return (
+    HEADER +
+    '/** Base props shared by every platform (AST-082 FR7). */\n' +
+    'export interface AstryxSharedBaseProps {\n  id?: string;\n  isHidden?: boolean;\n}\n' +
+    [...typeDecls, ...props].join('\n') +
+    '\n'
+  );
+}
+
+function reExports(contracts: readonly ComponentContract[]): string {
+  const names = new Set<string>(['AstryxSharedBaseProps']);
+  for (const contract of contracts) {
+    Object.keys(contract.types).forEach(name => names.add(name));
+    names.add(`${contract.name}CoreProps`);
+  }
+  return `export type {${[...names].join(', ')}} from './core.js';\n`;
+}
+
+function platformFile(
+  contracts: readonly ComponentContract[],
+  platform: NativePlatform | null,
+): string {
+  const imports = `import type {${contracts.map(c => `${c.name}CoreProps`).join(', ')}} from './core.js';\n`;
+  const components = contracts.map(contract => {
+    const extra = platform ? (contract.platforms[platform] ?? {}) : {};
+    const body = Object.keys(extra).length > 0 ? `\n  ${members(extra)}\n` : '';
+    const scope = platform
+      ? `core contract plus the ${platform} contract`
+      : 'core contract only';
+    return (
+      `/** ${contract.name} props: ${scope}. */\n` +
+      `export interface ${contract.name}Props extends ${contract.name}CoreProps {${body}}\n` +
+      `export declare function ${contract.name}(props: ${contract.name}Props): unknown;`
+    );
+  });
+  return HEADER + imports + reExports(contracts) + components.join('\n') + '\n';
+}
+
+/** Returns file name to contents, relative to the types output folder. */
+export function generateTypeScript(
+  contracts: readonly ComponentContract[],
+): Record<string, string> {
+  const files: Record<string, string> = {
+    'core.d.ts': coreFile(contracts),
+    'shared.d.ts': platformFile(contracts, null),
+  };
+  for (const platform of NATIVE_PLATFORMS) {
+    files[`${platform}.d.ts`] = platformFile(contracts, platform);
+  }
+  return files;
+}

package/src/contract/index.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract/index.ts
+ * @input Core component documentation, supplied by the caller
+ * @output Contracts for every native component, checked, plus the generators
+ * @position Build-time entry (`@astryxdesign/native/contract`). Reads core
+ *   documentation as data; nothing here runs in an app
+ */
+
+import {NATIVE_COMPONENTS} from '../components/index.js';
+import {fromComponentDoc, type ComponentDocLike} from './fromComponentDoc.js';
+import {checkContract, type ContractIssue} from './rules.js';
+import type {ComponentContract} from './types.js';
+
+export {fromComponentDoc} from './fromComponentDoc.js';
+export type {ComponentDocLike, NativeAdditions} from './fromComponentDoc.js';
+export {generateSwift} from './generateSwift.js';
+export {generateTypeScript} from './generateTypeScript.js';
+export {parseDocType} from './parseDocType.js';
+export {checkContract, coreNameProblem} from './rules.js';
+export type {ContractIssue} from './rules.js';
+export type * from './types.js';
+
+/** Loads one core component's documentation by component name. */
+export type ComponentDocLoader = (name: string) => Promise<ComponentDocLike>;
+
+export interface BuiltContracts {
+  readonly contracts: readonly ComponentContract[];
+  readonly warnings: readonly ContractIssue[];
+}
+
+/** Builds and checks every native component contract; throws on any error. */
+export async function buildContracts(
+  loadDoc: ComponentDocLoader,
+): Promise<BuiltContracts> {
+  const contracts: ComponentContract[] = [];
+  const warnings: ContractIssue[] = [];
+  const errors: ContractIssue[] = [];
+  for (const additions of NATIVE_COMPONENTS) {
+    const contract = fromComponentDoc(await loadDoc(additions.name), additions);
+    for (const issue of checkContract(contract)) {
+      (issue.level === 'error' ? errors : warnings).push(issue);
+    }
+    contracts.push(contract);
+  }
+  if (errors.length > 0) {
+    throw new Error(
+      `Native contracts are invalid:\n${errors.map(e => `  ${e.message}`).join('\n')}`,
+    );
+  }
+  return {contracts, warnings};
+}

package/src/contract/names.ts

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract/names.ts
+ * @input None
+ * @output Name lists the AST-082 FR8 rules check against
+ * @position Data for contract/rules.ts and contract/fromComponentDoc.ts
+ */
+
+export const SWIFT_KEYWORDS: ReadonlySet<string> = new Set(
+  (
+    'associatedtype class deinit enum extension fileprivate func import init inout ' +
+    'internal let open operator private precedencegroup protocol public rethrows ' +
+    'static struct subscript typealias var break case catch continue default defer ' +
+    'do else fallthrough for guard if in repeat return throw switch where while Any ' +
+    'as await false is nil self Self super throws true try'
+  ).split(' '),
+);
+
+export const KOTLIN_KEYWORDS: ReadonlySet<string> = new Set(
+  (
+    'as break class continue do else false for fun if in interface is null object ' +
+    'package return super this throw true try typealias typeof val var when while'
+  ).split(' '),
+);
+
+/**
+ * Names each platform toolkit already uses with its own meaning. A core prop
+ * must not take one of them unless Astryx reclaims it (RECLAIMED).
+ */
+export const TOOLKIT_NAMES: Readonly<Record<string, ReadonlySet<string>>> = {
+  web: new Set([
+    'children',
+    'className',
+    'style',
+    'title',
+    'hidden',
+    'role',
+    'tabIndex',
+    'dir',
+    'slot',
+    'is',
+    'key',
+    'ref',
+    'onChange',
+    'color',
+    'content',
+  ]),
+  reactNative: new Set([
+    'style',
+    'testID',
+    'nativeID',
+    'onPress',
+    'onLongPress',
+    'onLayout',
+    'accessibilityLabel',
+    'accessibilityHint',
+    'accessibilityRole',
+    'accessibilityState',
+    'accessible',
+    'hitSlop',
+    'pointerEvents',
+    'disabled',
+    'editable',
+    'numberOfLines',
+    'onChangeText',
+    'selectable',
+  ]),
+  swiftUI: new Set([
+    'body',
+    'disabled',
+    'hidden',
+    'opacity',
+    'frame',
+    'tint',
+    'font',
+    'background',
+    'overlay',
+    'accessibilityLabel',
+    'accessibilityHint',
+    'accessibilityIdentifier',
+  ]),
+  compose: new Set([
+    'modifier',
+    'enabled',
+    'onClick',
+    'colors',
+    'testTag',
+    'contentDescription',
+  ]),
+};
+
+/**
+ * Web names Astryx deliberately takes over for a component-owned concept
+ * (AST-082 FR8). The platform's own meaning is removed from that component's
+ * base props.
+ */
+export const RECLAIMED: ReadonlySet<string> = new Set([
+  'onChange',
+  'title',
+  'color',
+  'content',
+]);

package/src/contract/parseDocType.test.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {parseDocType} from './parseDocType.js';
+
+describe('parseDocType', () => {
+  it('reads portable forms', () => {
+    expect(parseDocType('string')).toEqual({ok: true, type: {kind: 'string'}});
+    expect(parseDocType("'sm' | 'md' | 'lg'")).toEqual({
+      ok: true,
+      type: {kind: 'enum', values: ['sm', 'md', 'lg']},
+    });
+    expect(parseDocType('SelectorOption[]')).toEqual({
+      ok: true,
+      type: {kind: 'array', of: {kind: 'named', name: 'SelectorOption'}},
+    });
+    expect(parseDocType('(value: string) => void')).toEqual({
+      ok: true,
+      type: {kind: 'fn', args: [{kind: 'string'}]},
+    });
+    expect(
+      parseDocType("{type: 'error' | 'warning', message?: string}"),
+    ).toEqual({
+      ok: true,
+      type: {
+        kind: 'record',
+        fields: {
+          type: {
+            type: {kind: 'enum', values: ['error', 'warning']},
+            optional: false,
+          },
+          message: {type: {kind: 'string'}, optional: true},
+        },
+      },
+    });
+  });
+
+  it.each([
+    ['ReactNode', 'free-form content'],
+    ['IconType | ReactNode', 'web icon component'],
+    ['(option: SelectorOptionData) => ReactNode', 'render function'],
+    ['(event: MouseEvent) => void', 'DOM event'],
+    ['StyleXStyles', 'web styling input'],
+    ['number | string', 'union of different kinds'],
+  ])('keeps %s out of the core', (type, reason) => {
+    const parsed = parseDocType(type);
+    expect(parsed.ok).toBe(false);
+    if (!parsed.ok) {
+      expect(parsed.reason).toContain(reason);
+    }
+  });
+});

package/src/contract/parseDocType.ts

@@ -0,0 +1,211 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract/parseDocType.ts
+ * @input A prop's type string as a component's .doc.mjs documents it
+ * @output A portable PropType, or the reason the type has no portable form
+ * @position Reads core documentation into the contract model (AST-082 FR4)
+ */
+
+import type {PropSpec, PropType} from './types.js';
+
+export type ParsedType =
+  | {readonly ok: true; readonly type: PropType}
+  | {readonly ok: false; readonly reason: string};
+
+/** Web-only types, keyed by name, with the reason each has no native form. */
+const WEB_ONLY_TYPES: Readonly<Record<string, string>> = {
+  ReactNode: 'free-form content; use a typed slot in the core',
+  ReactElement: 'free-form content; use a typed slot in the core',
+  'JSX.Element': 'free-form content; use a typed slot in the core',
+  StyleXStyles: 'web styling input',
+  CSSProperties: 'web styling input',
+  SizeValue: 'CSS length',
+  IconType: 'web icon component; native icons use shared icon names',
+  ElementType: 'web element choice',
+  ComponentType: 'web component reference',
+  LinkComponentType: 'web link component',
+  AriaRole: 'web accessibility attribute',
+  MouseEvent: 'DOM event',
+  FocusEvent: 'DOM event',
+  KeyboardEvent: 'DOM event',
+  PointerEvent: 'DOM event',
+  ChangeEvent: 'DOM event',
+  DragEvent: 'DOM event',
+  ClipboardEvent: 'DOM event',
+};
+
+const ok = (type: PropType): ParsedType => ({ok: true, type});
+const no = (reason: string): ParsedType => ({ok: false, reason});
+
+/** Splits on a separator at bracket depth zero, ignoring quoted text. */
+function splitTop(text: string, separator: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let quote: string | null = null;
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (quote) {
+      if (ch === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (ch === "'" || ch === '"') {
+      quote = ch;
+    } else if (text.startsWith('=>', i)) {
+      // An arrow is not a closing angle bracket.
+      if (depth === 0 && separator === '=>') {
+        parts.push(text.slice(start, i));
+        start = i + 2;
+      }
+      i += 1;
+    } else if ('([{<'.includes(ch)) {
+      depth++;
+    } else if (')]}>'.includes(ch)) {
+      depth--;
+    } else if (depth === 0 && text.startsWith(separator, i)) {
+      parts.push(text.slice(start, i));
+      start = i + separator.length;
+      i += separator.length - 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts.map(part => part.trim()).filter(part => part.length > 0);
+}
+
+/** True when the first `(` closes at the last character, as in `(A | B)`. */
+function isWrappedInParens(text: string): boolean {
+  if (!text.startsWith('(') || !text.endsWith(')')) {
+    return false;
+  }
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === '(') {
+      depth++;
+    } else if (text[i] === ')') {
+      depth--;
+    }
+    if (depth === 0 && i < text.length - 1) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function stripOuterParens(text: string): string {
+  let t = text.trim();
+  while (isWrappedInParens(t)) {
+    t = t.slice(1, -1).trim();
+  }
+  return t;
+}
+
+function parseRecord(body: string): ParsedType {
+  const fields: Record<string, PropSpec> = {};
+  for (const member of splitTop(body, ',').flatMap(part =>
+    splitTop(part, ';'),
+  )) {
+    const match = /^([A-Za-z_$][\w$]*)(\?)?\s*:\s*([\s\S]+)$/.exec(member);
+    if (!match) {
+      return no(`record member "${member}" is not a plain field`);
+    }
+    const parsed = parseDocType(match[3]);
+    if (!parsed.ok) {
+      return no(`field "${match[1]}": ${parsed.reason}`);
+    }
+    fields[match[1]] = {type: parsed.type, optional: match[2] === '?'};
+  }
+  return ok({kind: 'record', fields});
+}
+
+function parseFunction(text: string): ParsedType | null {
+  const arrow = splitTop(text, '=>');
+  if (arrow.length !== 2 || !arrow[0].startsWith('(')) {
+    return null;
+  }
+  const returns = arrow[1].trim();
+  if (returns !== 'void') {
+    return no(
+      /React|ReactNode|JSX/.test(returns)
+        ? 'render function; it returns web UI'
+        : 'callback returns a value; only void callbacks are portable today',
+    );
+  }
+  const params = arrow[0].slice(1, -1).trim();
+  const args: PropType[] = [];
+  for (const param of params ? splitTop(params, ',') : []) {
+    const match = /^([A-Za-z_$][\w$]*)\??\s*:\s*([\s\S]+)$/.exec(param);
+    const parsed = parseDocType(match ? match[2] : param);
+    if (!parsed.ok) {
+      return no(`callback argument: ${parsed.reason}`);
+    }
+    args.push(parsed.type);
+  }
+  return ok({kind: 'fn', args});
+}
+
+/**
+ * Parses a documented type string. Supported portable forms: `string`,
+ * `number`, `boolean`, closed string unions, arrays, plain object literals,
+ * callbacks with portable arguments, and named types. A union of different
+ * kinds has no Swift or Kotlin form.
+ */
+export function parseDocType(raw: string): ParsedType {
+  const text = stripOuterParens(raw.replace(/\s+/g, ' ').trim());
+  if (text === '') {
+    return no('no documented type');
+  }
+
+  const fn = parseFunction(text);
+  if (fn) {
+    return fn;
+  }
+
+  const members = splitTop(text, '|').filter(
+    m => m !== 'undefined' && m !== 'null',
+  );
+  if (members.length > 1) {
+    if (members.every(m => /^'[^']*'$/.test(m))) {
+      return ok({kind: 'enum', values: members.map(m => m.slice(1, -1))});
+    }
+    const webOnly = members.find(m => WEB_ONLY_TYPES[m] != null);
+    if (webOnly) {
+      return no(WEB_ONLY_TYPES[webOnly]);
+    }
+    return no('a union of different kinds has no Swift or Kotlin form');
+  }
+  const t = members[0] ?? '';
+
+  if (t === 'string' || t === 'number' || t === 'boolean') {
+    return ok({kind: t});
+  }
+  if (/^'[^']*'$/.test(t)) {
+    return ok({kind: 'enum', values: [t.slice(1, -1)]});
+  }
+  if (WEB_ONLY_TYPES[t] != null) {
+    return no(WEB_ONLY_TYPES[t]);
+  }
+
+  const generic = /^(?:Readonly)?Array<([\s\S]+)>$/.exec(t);
+  if (t.endsWith('[]') || generic) {
+    const inner = parseDocType(generic ? generic[1] : t.slice(0, -2));
+    return inner.ok
+      ? ok({kind: 'array', of: inner.type})
+      : no(`array item: ${inner.reason}`);
+  }
+  if (t.startsWith('{') && t.endsWith('}')) {
+    return parseRecord(t.slice(1, -1));
+  }
+  if (
+    /^(?:React\.)?(?:Ref|RefObject|MutableRefObject)</.test(t) ||
+    /^HTML\w*Element$/.test(t)
+  ) {
+    return no('web element reference');
+  }
+  if (/^[A-Z][\w$]*$/.test(t)) {
+    return ok({kind: 'named', name: t});
+  }
+  return no(`unsupported type "${t}"`);
+}

package/src/contract/rules.ts

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract/rules.ts
+ * @input A component contract
+ * @output Naming and portability issues under AST-082 FR4 and FR8
+ * @position Run by the generator before it writes any binding; an error stops
+ *   generation
+ */
+
+import {NATIVE_PLATFORMS} from '../platforms.js';
+import {
+  KOTLIN_KEYWORDS,
+  RECLAIMED,
+  SWIFT_KEYWORDS,
+  TOOLKIT_NAMES,
+} from './names.js';
+import type {ComponentContract, PropMap, PropType} from './types.js';
+
+export interface ContractIssue {
+  readonly level: 'error' | 'warning';
+  readonly rule:
+    | 'core-is-portable'
+    | 'name-keyword'
+    | 'name-toolkit'
+    | 'platform-shadows-core'
+    | 'same-name-different-meaning'
+    | 'unknown-type';
+  readonly message: string;
+}
+
+/** Why a core prop name is not allowed, or null when it is. */
+export function coreNameProblem(name: string): string | null {
+  if (SWIFT_KEYWORDS.has(name)) {
+    return `"${name}" is a Swift keyword`;
+  }
+  if (KOTLIN_KEYWORDS.has(name)) {
+    return `"${name}" is a Kotlin keyword`;
+  }
+  if (RECLAIMED.has(name)) {
+    return null;
+  }
+  for (const [toolkit, names] of Object.entries(TOOLKIT_NAMES)) {
+    if (names.has(name)) {
+      return `"${name}" already means something else in ${toolkit}`;
+    }
+  }
+  return null;
+}
+
+function namedTypesIn(type: PropType, into: Set<string>): Set<string> {
+  if (type.kind === 'named') {
+    into.add(type.name);
+  } else if (type.kind === 'array') {
+    namedTypesIn(type.of, into);
+  } else if (type.kind === 'fn') {
+    type.args.forEach(arg => namedTypesIn(arg, into));
+  } else if (type.kind === 'record') {
+    Object.values(type.fields).forEach(field => namedTypesIn(field.type, into));
+  }
+  return into;
+}
+
+export function checkContract(contract: ComponentContract): ContractIssue[] {
+  const issues: ContractIssue[] = [];
+  const add = (
+    level: ContractIssue['level'],
+    rule: ContractIssue['rule'],
+    message: string,
+  ) => issues.push({level, rule, message: `${contract.name}: ${message}`});
+
+  const referenced = new Set<string>();
+  const collect = (props: PropMap) =>
+    Object.values(props).forEach(spec => namedTypesIn(spec.type, referenced));
+
+  for (const name of Object.keys(contract.core)) {
+    const problem = coreNameProblem(name);
+    if (problem) {
+      add(
+        'error',
+        SWIFT_KEYWORDS.has(name) || KOTLIN_KEYWORDS.has(name)
+          ? 'name-keyword'
+          : 'name-toolkit',
+        `core prop ${problem}`,
+      );
+    }
+  }
+  collect(contract.core);
+
+  const seen = new Map<string, {platform: string; type: string}>();
+  for (const platform of NATIVE_PLATFORMS) {
+    const props = contract.platforms[platform] ?? {};
+    collect(props);
+    for (const [name, spec] of Object.entries(props)) {
+      if (name in contract.core) {
+        add(
+          'error',
+          'platform-shadows-core',
+          `${platform} prop "${name}" reuses a core prop name`,
+        );
+      }
+      if (SWIFT_KEYWORDS.has(name) || KOTLIN_KEYWORDS.has(name)) {
+        add(
+          'error',
+          'name-keyword',
+          `${platform} prop "${name}" is a Swift or Kotlin keyword`,
+        );
+      }
+      const type = JSON.stringify(spec.type);
+      const earlier = seen.get(name);
+      if (earlier && earlier.type !== type) {
+        add(
+          'warning',
+          'same-name-different-meaning',
+          `"${name}" has different values on ${earlier.platform} and ${platform}; ` +
+            'allowed in platform-scoped types, never in a merged type',
+        );
+      }
+      if (!earlier) {
+        seen.set(name, {platform, type});
+      }
+    }
+  }
+
+  Object.values(contract.types).forEach(collect);
+  for (const name of referenced) {
+    if (!(name in contract.types)) {
+      add('error', 'unknown-type', `type "${name}" has no definition`);
+    }
+  }
+  return issues;
+}