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

package/package.json

@@ -1,11 +1,78 @@
 {
   "name": "@astryxdesign/native",
-  "version": "0.0.0-bootstrap.1",
-  "description": "Placeholder published to claim the npm name during trusted publishing setup. Do not install.",
-  "homepage": "https://github.com/facebook/astryx",
+  "version": "0.7.4-canary.720bb10",
+  "description": "Experimental native platforms for Astryx (iOS, Android, macOS, Windows) — published to npm only under the @canary dist-tag; never released as a stable (latest) version.",
+  "author": "Meta Open Source",
   "license": "MIT",
+  "homepage": "https://github.com/facebook/astryx#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/facebook/astryx.git"
+    "url": "git+https://github.com/facebook/astryx.git",
+    "directory": "packages/native"
+  },
+  "bugs": {
+    "url": "https://github.com/facebook/astryx/issues"
+  },
+  "keywords": [
+    "astryx",
+    "native",
+    "experimental",
+    "design-system"
+  ],
+  "astryx": {
+    "canaryOnly": true,
+    "_comment": "Published ONLY to the @canary dist-tag (see .github/workflows/release.yml). Never published as a stable `latest` release. `private: true` is intentional and must stay — it is npm's hard guarantee against an accidental stable publish."
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "apple",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./components": {
+      "ios": {
+        "types": "./dist/types/ios.d.ts"
+      },
+      "android": {
+        "types": "./dist/types/android.d.ts"
+      },
+      "macos": {
+        "types": "./dist/types/macos.d.ts"
+      },
+      "windows": {
+        "types": "./dist/types/windows.d.ts"
+      },
+      "shared": {
+        "types": "./dist/types/shared.d.ts"
+      },
+      "types": "./dist/types/shared.d.ts"
+    },
+    "./contract": {
+      "source": "./src/contract/index.ts",
+      "types": "./dist/contract/index.d.ts",
+      "default": "./dist/contract/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@astryxdesign/core": "0.7.4-canary.720bb10"
+  },
+  "devDependencies": {
+    "@astryxdesign/core": "0.7.4-canary.720bb10"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean-dist.mjs && tsc --project tsconfig.build.json && node scripts/generate.mjs --types",
+    "generate:apple": "pnpm build && node scripts/generate.mjs --apple",
+    "test": "vitest run --root ../.. packages/native",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
   }
-}
+}

package/src/components/Selector.ts

@@ -0,0 +1,50 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file components/Selector.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core Selector contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Selector documentation
+ */
+
+import type {NativeAdditions} from '../contract/fromComponentDoc.js';
+
+export const selector: NativeAdditions = {
+  name: 'Selector',
+  baseTarget: 'trigger',
+  typeNames: {SelectorOption: 'SelectorOption'},
+  types: {
+    // The portable part of core's option data. Its rich description, icon,
+    // and secondary control are web-only until typed slots exist.
+    SelectorOption: {
+      value: {type: {kind: 'string'}},
+      label: {type: {kind: 'string'}, optional: true},
+      disabled: {type: {kind: 'boolean'}, optional: true},
+    },
+  },
+  webOnly: {
+    presentation:
+      'web presentation choice; native platforms use their own control (FR11)',
+  },
+  platforms: {
+    ios: {
+      menuStyle: {
+        type: {kind: 'enum', values: ['popUp', 'pullDown']},
+        optional: true,
+      },
+    },
+    macos: {
+      menuStyle: {
+        type: {kind: 'enum', values: ['popUp', 'pullDown']},
+        optional: true,
+      },
+    },
+    android: {
+      menuStyle: {
+        type: {kind: 'enum', values: ['dropdown', 'bottomSheet']},
+        optional: true,
+      },
+    },
+  },
+};

package/src/components/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file components/index.ts
+ * @input None
+ * @output Every component the native package adds to, by core component name
+ * @position The generator walks this list; each entry pairs with core's
+ *   `<Name>/<Name>.doc.mjs`
+ */
+
+import type {NativeAdditions} from '../contract/fromComponentDoc.js';
+import {selector} from './Selector.js';
+
+export const NATIVE_COMPONENTS: readonly NativeAdditions[] = [selector];

package/src/contract/contracts.test.ts

@@ -0,0 +1,150 @@
+// 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';
+
+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('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',
+    );
+  });
+});

package/src/contract/fromComponentDoc.ts

@@ -0,0 +1,131 @@
+// 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,
+  WebOnlyProp,
+} from './types.js';
+import type {NativePlatform} from '../platforms.js';
+
+/** The subset of a ComponentDoc this reader needs. */
+export interface ComponentDocLike {
+  readonly name: string;
+  readonly props?: ReadonlyArray<{
+    readonly name: string;
+    readonly type?: unknown;
+    readonly required?: boolean;
+    readonly description?: unknown;
+  }>;
+}
+
+/** What the native package adds to one core component. */
+export interface NativeAdditions {
+  readonly name: string;
+  readonly baseTarget: BaseTarget;
+  /**
+   * 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>>>;
+  /**
+   * 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>>;
+}
+
+export function fromComponentDoc(
+  doc: ComponentDocLike,
+  additions: NativeAdditions,
+): ComponentContract {
+  const core: Record<string, PropSpec> = {};
+  const webOnly: WebOnlyProp[] = [];
+  const types = additions.types ?? {};
+
+  for (const prop of doc.props ?? []) {
+    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 parsed = parseDocType(String(prop.type ?? ''));
+    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);
+    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,
+      ...(typeof prop.description === 'string' ? {doc: prop.description} : {}),
+    };
+  }
+
+  return {
+    name: additions.name,
+    baseTarget: additions.baseTarget,
+    types,
+    core,
+    platforms: additions.platforms ?? {},
+    webOnly,
+  };
+}

package/src/contract/generateSwift.ts

@@ -0,0 +1,170 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract/generateSwift.ts
+ * @input Component contracts
+ * @output Swift sources for the Apple platforms: shared base props and one file
+ *   per component, with the iOS and macOS contracts behind `#if os(...)`
+ * @position Produces the Swift binding (AST-082 FR5). Generated files are
+ *   committed under apple/ so a Swift package can pin a commit
+ */
+
+import {SWIFT_KEYWORDS} from './names.js';
+import type {ComponentContract, PropMap, PropType} from './types.js';
+
+const HEADER = '// Generated by @astryxdesign/native. Do not edit.\n';
+const APPLE_PLATFORMS = [
+  {platform: 'ios', condition: 'os(iOS)'},
+  {platform: 'macos', condition: 'os(macOS)'},
+] as const;
+
+const camel = (text: string) =>
+  text.replace(/[-_ ]+([a-zA-Z0-9])/g, (_, ch: string) => ch.toUpperCase());
+const pascal = (text: string) =>
+  camel(text).replace(/^./, ch => ch.toUpperCase());
+const ident = (name: string) =>
+  SWIFT_KEYWORDS.has(name) ? `\`${name}\`` : name;
+
+function caseName(value: string): string {
+  const name = camel(value.replace(/[^A-Za-z0-9_-]/g, '-'));
+  return ident(/^[0-9]/.test(name) ? `v${name}` : name || 'empty');
+}
+
+/** Collects nested declarations (enums, structs) while rendering types. */
+class SwiftWriter {
+  readonly decls: string[] = [];
+
+  type(owner: string, prop: string, type: PropType): string {
+    switch (type.kind) {
+      case 'string':
+        return 'String';
+      case 'number':
+        return 'Double';
+      case 'boolean':
+        return 'Bool';
+      case 'enum': {
+        const name = `${owner}${pascal(prop)}`;
+        const cases = type.values.map(
+          value => `  case ${caseName(value)} = "${value}"`,
+        );
+        this.decls.push(
+          `public enum ${name}: String, CaseIterable, Sendable {\n${cases.join('\n')}\n}`,
+        );
+        return name;
+      }
+      case 'array':
+        return `[${this.type(owner, prop, type.of)}]`;
+      case 'record': {
+        const name = `${owner}${pascal(prop)}`;
+        this.decls.push(this.struct(name, type.fields, 'Equatable, Sendable'));
+        return name;
+      }
+      case 'fn':
+        return `(${type.args.map((arg, i) => this.type(owner, `${prop}Arg${i}`, arg)).join(', ')}) -> Void`;
+      case 'named':
+        return type.name;
+    }
+  }
+
+  fields(
+    owner: string,
+    props: PropMap,
+  ): Array<{name: string; decl: string; param: string; assign: string}> {
+    return Object.entries(props).map(([name, spec]) => {
+      const base = this.type(owner, name, spec.type);
+      const optional = spec.type.kind === 'fn' ? `(${base})?` : `${base}?`;
+      const swiftType = spec.optional ? optional : base;
+      return {
+        name,
+        decl: `  public var ${ident(name)}: ${swiftType}`,
+        param: `${name}: ${spec.type.kind === 'fn' && !spec.optional ? `@escaping ${swiftType}` : swiftType}${spec.optional ? ' = nil' : ''}`,
+        assign: `    self.${name} = ${ident(name)}`,
+      };
+    });
+  }
+
+  struct(
+    name: string,
+    props: PropMap,
+    conformances: string | null,
+    extra: string[] = [],
+  ): string {
+    const fields = this.fields(name, props);
+    const head = conformances
+      ? `public struct ${name}: ${conformances} {`
+      : `public struct ${name} {`;
+    return [
+      head,
+      ...extra,
+      ...fields.map(field => field.decl),
+      `  public init(${fields.map(field => field.param).join(', ')}) {`,
+      ...fields.map(field => field.assign),
+      '  }',
+      '}',
+    ].join('\n');
+  }
+}
+
+function componentFile(contract: ComponentContract): string {
+  const shared = new SwiftWriter();
+  const typeDecls = Object.entries(contract.types).map(([name, fields]) =>
+    shared.struct(name, fields, 'Equatable, Sendable'),
+  );
+  // Core enums and records are declared once, outside the platform blocks.
+  shared.fields(`${contract.name}`, contract.core);
+
+  const variants = APPLE_PLATFORMS.map(({platform, condition}) => {
+    const writer = new SwiftWriter();
+    const extra = contract.platforms[platform] ?? {};
+    const fields = writer.fields(contract.name, {...contract.core, ...extra});
+    // Core-prop declarations already live outside the platform blocks; keep
+    // only the declarations this platform's own props need.
+    writer.decls.length = 0;
+    writer.fields(contract.name, extra);
+    const struct = [
+      `public struct ${contract.name}Props {`,
+      `  /// Base props attach to this part on every platform.`,
+      `  public static let baseTarget: AstryxBaseTarget = .${contract.baseTarget}`,
+      '  public var base: AstryxBaseProps',
+      ...fields.map(field => field.decl),
+      `  public init(${[...fields.map(field => field.param), 'base: AstryxBaseProps = AstryxBaseProps()'].join(', ')}) {`,
+      ...fields.map(field => field.assign),
+      '    self.base = base',
+      '  }',
+      '}',
+    ].join('\n');
+    return `#if ${condition}\n${[...writer.decls, struct].join('\n')}\n#endif`;
+  });
+
+  return (
+    HEADER + [...typeDecls, ...shared.decls, ...variants].join('\n') + '\n'
+  );
+}
+
+const BASE_FILE =
+  HEADER +
+  [
+    'public enum AstryxBaseTarget: String, Sendable { case root, trigger, control, container }',
+    '',
+    '/// Base props shared by every platform (AST-082 FR7).',
+    'public struct AstryxBaseProps: Equatable, Sendable {',
+    '  public var id: String?',
+    '  public var isHidden: Bool?',
+    '  public init(id: String? = nil, isHidden: Bool? = nil) {',
+    '    self.id = id',
+    '    self.isHidden = isHidden',
+    '  }',
+    '}',
+  ].join('\n') +
+  '\n';
+
+/** Returns file name to contents, relative to the generated Swift folder. */
+export function generateSwift(
+  contracts: readonly ComponentContract[],
+): Record<string, string> {
+  const files: Record<string, string> = {'AstryxBase.swift': BASE_FILE};
+  for (const contract of contracts) {
+    files[`${contract.name}.swift`] = componentFile(contract);
+  }
+  return files;
+}