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

package/src/contract/types.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file contract/types.ts
+ * @input None (pure type definitions)
+ * @output The contract model: portable prop types, prop specs, and component contracts
+ * @position Foundation of the contract generator; parseDocType produces these,
+ *   generators consume them
+ */
+
+import type {NativePlatform} from '../platforms.js';
+
+/** A prop type every supported platform language can express (AST-082 FR4). */
+export type PropType =
+  | {kind: 'string'}
+  | {kind: 'number'}
+  | {kind: 'boolean'}
+  | {kind: 'enum'; values: readonly string[]}
+  | {kind: 'array'; of: PropType}
+  | {kind: 'record'; fields: Readonly<Record<string, PropSpec>>}
+  | {kind: 'fn'; args: readonly PropType[]}
+  | {kind: 'named'; name: string};
+
+export interface PropSpec {
+  readonly type: PropType;
+  readonly optional?: boolean;
+  readonly doc?: string;
+}
+
+export type PropMap = Readonly<Record<string, PropSpec>>;
+
+/** The part of a component its base props attach to (AST-082 FR7). */
+export type BaseTarget = 'root' | 'trigger' | 'control' | 'container';
+
+/** A web prop left out of the core contract, with the reason. */
+export interface WebOnlyProp {
+  readonly name: string;
+  readonly reason: string;
+}
+
+export interface ComponentContract {
+  readonly name: string;
+  readonly baseTarget: BaseTarget;
+  /** Named record types the contract references, such as an option shape. */
+  readonly types: Readonly<Record<string, PropMap>>;
+  /** Shared on every platform that offers the component. */
+  readonly core: PropMap;
+  /** Added per native platform; never removes or renames a core prop. */
+  readonly platforms: Readonly<Partial<Record<NativePlatform, PropMap>>>;
+  /** Core-doc props that stay in the web contract. */
+  readonly webOnly: readonly WebOnlyProp[];
+}

package/src/icons/defaults.test.ts

@@ -0,0 +1,47 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import fs from 'node:fs';
+import {execFileSync} from 'node:child_process';
+import {describe, expect, it} from 'vitest';
+import {readCoreIconNames} from '../../scripts/core-docs.mjs';
+import {
+  BUILTIN_ICON_NAMES,
+  NATIVE_ICON_DEFAULTS,
+  SF_SYMBOL_NAMES,
+} from './defaults.js';
+
+// The system's SF Symbols catalog; present on macOS only.
+const SF_CATALOG =
+  '/System/Library/CoreServices/CoreGlyphs.bundle/Contents/Resources/name_availability.plist';
+
+describe('native icon defaults', () => {
+  it("lists exactly core's built-in icon names", () => {
+    expect([...BUILTIN_ICON_NAMES].sort()).toEqual(readCoreIconNames().sort());
+  });
+
+  it('gives every built-in name a default on each supported platform', () => {
+    for (const platform of ['ios', 'macos', 'android'] as const) {
+      expect(Object.keys(NATIVE_ICON_DEFAULTS[platform]).sort()).toEqual(
+        [...BUILTIN_ICON_NAMES].sort(),
+      );
+    }
+  });
+
+  it.skipIf(!fs.existsSync(SF_CATALOG))(
+    'names only SF Symbols the system has',
+    () => {
+      const json = execFileSync(
+        'plutil',
+        ['-convert', 'json', '-o', '-', SF_CATALOG],
+        {
+          maxBuffer: 16 * 1024 * 1024,
+        },
+      ).toString();
+      const symbols = JSON.parse(json).symbols as Record<string, string>;
+      const missing = Object.values(SF_SYMBOL_NAMES).filter(
+        name => symbols[name] == null,
+      );
+      expect(missing).toEqual([]);
+    },
+  );
+});

package/src/icons/defaults.ts

@@ -0,0 +1,136 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file icons/defaults.ts
+ * @input None
+ * @output Shared icon names and each native platform's default system symbol
+ * @position Native icon defaults (AST-082 FR17, DEC-10). An icon the app or
+ *   theme defines replaces these
+ */
+
+import type {PlatformIcon} from '../theme/defineNativeTheme.js';
+
+/**
+ * Astryx's built-in icon names. Until core's portable entry carries them,
+ * a test keeps this list equal to core's `IconName` union.
+ */
+export const BUILTIN_ICON_NAMES = [
+  'close',
+  'chevronDown',
+  'chevronLeft',
+  'chevronRight',
+  'chevronsLeft',
+  'chevronsRight',
+  'check',
+  'success',
+  'error',
+  'warning',
+  'info',
+  'calendar',
+  'clock',
+  'externalLink',
+  'menu',
+  'moreHorizontal',
+  'search',
+  'upload',
+  'arrowUp',
+  'arrowDown',
+  'arrowsUpDown',
+  'funnel',
+  'eyeSlash',
+  'viewColumns',
+  'copy',
+  'checkDouble',
+  'wrench',
+  'stop',
+  'microphone',
+] as const;
+
+export type BuiltinIconName = (typeof BUILTIN_ICON_NAMES)[number];
+
+/** SF Symbols, shared by iOS and macOS. */
+const SF_SYMBOLS: Record<BuiltinIconName, string> = {
+  close: 'xmark',
+  chevronDown: 'chevron.down',
+  chevronLeft: 'chevron.left',
+  chevronRight: 'chevron.right',
+  chevronsLeft: 'chevron.left.2',
+  chevronsRight: 'chevron.right.2',
+  check: 'checkmark',
+  success: 'checkmark.circle.fill',
+  error: 'exclamationmark.circle.fill',
+  warning: 'exclamationmark.triangle.fill',
+  info: 'info.circle.fill',
+  calendar: 'calendar',
+  clock: 'clock',
+  externalLink: 'arrow.up.right.square',
+  menu: 'line.3.horizontal',
+  moreHorizontal: 'ellipsis',
+  search: 'magnifyingglass',
+  upload: 'square.and.arrow.up',
+  arrowUp: 'arrow.up',
+  arrowDown: 'arrow.down',
+  arrowsUpDown: 'arrow.up.arrow.down',
+  funnel: 'line.3.horizontal.decrease',
+  eyeSlash: 'eye.slash',
+  viewColumns: 'rectangle.split.3x1',
+  copy: 'doc.on.doc',
+  checkDouble: 'checkmark.message',
+  wrench: 'wrench.adjustable',
+  stop: 'stop.fill',
+  microphone: 'mic',
+};
+
+/** Material Symbols names for Android. */
+const MATERIAL_SYMBOLS: Record<BuiltinIconName, string> = {
+  close: 'close',
+  chevronDown: 'expand_more',
+  chevronLeft: 'chevron_left',
+  chevronRight: 'chevron_right',
+  chevronsLeft: 'keyboard_double_arrow_left',
+  chevronsRight: 'keyboard_double_arrow_right',
+  check: 'check',
+  success: 'check_circle',
+  error: 'error',
+  warning: 'warning',
+  info: 'info',
+  calendar: 'calendar_today',
+  clock: 'schedule',
+  externalLink: 'open_in_new',
+  menu: 'menu',
+  moreHorizontal: 'more_horiz',
+  search: 'search',
+  upload: 'upload',
+  arrowUp: 'arrow_upward',
+  arrowDown: 'arrow_downward',
+  arrowsUpDown: 'swap_vert',
+  funnel: 'filter_alt',
+  eyeSlash: 'visibility_off',
+  viewColumns: 'view_column',
+  copy: 'content_copy',
+  checkDouble: 'done_all',
+  wrench: 'build',
+  stop: 'stop',
+  microphone: 'mic',
+};
+
+const mapIcons = (
+  names: Record<BuiltinIconName, string>,
+  make: (name: string) => PlatformIcon,
+): Record<BuiltinIconName, PlatformIcon> =>
+  Object.fromEntries(
+    BUILTIN_ICON_NAMES.map(name => [name, make(names[name])]),
+  ) as Record<BuiltinIconName, PlatformIcon>;
+
+/**
+ * Default icons per native platform. Windows has no map yet, so it is not a
+ * supported platform for icons (FR17).
+ */
+export const NATIVE_ICON_DEFAULTS = {
+  ios: mapIcons(SF_SYMBOLS, systemName => ({systemName})),
+  macos: mapIcons(SF_SYMBOLS, systemName => ({systemName})),
+  android: mapIcons(MATERIAL_SYMBOLS, materialSymbol => ({materialSymbol})),
+} as const;
+
+export const SF_SYMBOL_NAMES: Readonly<Record<BuiltinIconName, string>> =
+  SF_SYMBOLS;

package/src/index.ts

@@ -0,0 +1,35 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input None
+ * @output The run-time API of @astryxdesign/native: platforms, native theme
+ *   configuration, and native icon defaults
+ * @position Package root. Experimental and canary-only (AST-082 FR15); component
+ *   types live at `@astryxdesign/native/components`
+ */
+
+export {
+  NATIVE_PLATFORMS,
+  SHARED_CONDITION,
+  isNativePlatform,
+} from './platforms.js';
+export type {NativePlatform} from './platforms.js';
+export {
+  compareVersions,
+  defineNativeTheme,
+  resolveNativeTheme,
+} from './theme/defineNativeTheme.js';
+export type {
+  DefineNativeThemeOptions,
+  DurableMaterial,
+  NativeTheme,
+  NativeThemeConfig,
+  PlatformEntry,
+  PlatformIcon,
+  PlatformVocabulary,
+  PortableThemeLike,
+  ResolvedNativeTheme,
+} from './theme/defineNativeTheme.js';
+export {BUILTIN_ICON_NAMES, NATIVE_ICON_DEFAULTS} from './icons/defaults.js';
+export type {BuiltinIconName} from './icons/defaults.js';

package/src/platforms.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file platforms.ts
+ * @input None
+ * @output The native platform names shared by contracts, types, themes, and icons
+ * @position Foundation; every other module keys platform data by these names
+ */
+
+/** Native platforms, in the order AST-082 lists them. */
+export const NATIVE_PLATFORMS = ['ios', 'android', 'macos', 'windows'] as const;
+
+export type NativePlatform = (typeof NATIVE_PLATFORMS)[number];
+
+/** Type-resolution condition that exposes only core contracts (AST-082 FR6). */
+export const SHARED_CONDITION = 'shared';
+
+export function isNativePlatform(value: string): value is NativePlatform {
+  return (NATIVE_PLATFORMS as readonly string[]).includes(value);
+}

package/src/theme/defineNativeTheme.test.ts

@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it, vi} from 'vitest';
+import {
+  compareVersions,
+  defineNativeTheme,
+  resolveNativeTheme,
+} from './defineNativeTheme.js';
+
+const theme = {name: 'brand', tokens: {'--color-accent': '#0064e0'}};
+
+describe('defineNativeTheme', () => {
+  it('scopes a version-specific material and resolves it per OS version', () => {
+    const native = defineNativeTheme(
+      theme,
+      {
+        material: 'translucent',
+        platforms: {
+          ios: [{minVersion: '26', material: 'liquidGlass'}],
+          android: [{material: 'opaque'}],
+        },
+      },
+      {onReport: () => {}},
+    );
+    expect(
+      resolveNativeTheme(native, {platform: 'ios', osVersion: '26.1'}).material,
+    ).toBe('liquidGlass');
+    expect(
+      resolveNativeTheme(native, {platform: 'ios', osVersion: '18.6'}).material,
+    ).toBe('translucent');
+    expect(
+      resolveNativeTheme(native, {platform: 'android', osVersion: '16'})
+        .material,
+    ).toBe('opaque');
+    expect(
+      resolveNativeTheme(native, {platform: 'windows', osVersion: '11'})
+        .material,
+    ).toBe('translucent');
+  });
+
+  it('rejects a platform feature outside the versions that have it', () => {
+    expect(() =>
+      defineNativeTheme(
+        theme,
+        {platforms: {ios: [{material: 'liquidGlass'}]}},
+        {onReport: () => {}},
+      ),
+    ).toThrow(/liquidGlass.*minVersion: '26'/);
+  });
+
+  it('reports web-only theme parts and keeps only the portable part', () => {
+    const report = vi.fn();
+    const webTheme = {
+      ...theme,
+      components: {Button: {root: {}}},
+      icons: {},
+      __onDark: {x: 1},
+    };
+    const native = defineNativeTheme(webTheme, {}, {onReport: report});
+    expect(report.mock.calls.map(call => String(call[0]))).toEqual([
+      expect.stringContaining('"components" is web-only'),
+      expect.stringContaining('"onDark" is web-only'),
+    ]);
+    expect(native.theme).toEqual(theme);
+  });
+
+  it('extends another native theme: durable members merge, platform lists replace', () => {
+    const base = defineNativeTheme(theme, {
+      material: 'opaque',
+      platforms: {android: [{material: 'translucent'}]},
+    });
+    const child = defineNativeTheme(
+      theme,
+      {platforms: {ios: [{material: 'opaque'}]}},
+      {extends: base},
+    );
+    expect(child.config.material).toBe('opaque');
+    expect(child.config.platforms?.android).toEqual([
+      {material: 'translucent'},
+    ]);
+    expect(child.config.platforms?.ios).toEqual([{material: 'opaque'}]);
+  });
+
+  it('compares dotted versions numerically', () => {
+    expect(compareVersions('26', '26.0.1')).toBeLessThan(0);
+    expect(compareVersions('10.15', '10.9')).toBeGreaterThan(0);
+  });
+});

package/src/theme/defineNativeTheme.ts

@@ -0,0 +1,224 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file theme/defineNativeTheme.ts
+ * @input A defined theme (its portable part) and native theme configuration
+ * @output A native theme, and its resolution for one platform and OS version
+ * @position Native theme configuration (AST-082 FR10, FR18). Builds on the
+ *   defined theme without changing it and never sets tokens
+ */
+
+import {NATIVE_PLATFORMS, type NativePlatform} from '../platforms.js';
+
+/**
+ * The portable part of a defined theme (AST-082 FR18). A core `DefinedTheme`
+ * satisfies it structurally, so native never imports core to accept one.
+ */
+export interface PortableThemeLike {
+  readonly name: string;
+  readonly tokens: Readonly<Record<string, string>>;
+  readonly localTokens?: Readonly<Record<string, string>>;
+}
+
+/** Durable outcomes a person sees; no platform feature names (DEC-5). */
+export type DurableMaterial = 'opaque' | 'translucent';
+
+export interface PlatformVocabulary {
+  ios: {material: DurableMaterial | 'liquidGlass'};
+  macos: {material: DurableMaterial | 'liquidGlass'};
+  android: {material: DurableMaterial};
+  windows: {material: DurableMaterial | 'mica' | 'acrylic'};
+}
+
+/** Platform icon reference, as data (AST-082 FR17). */
+export type PlatformIcon =
+  {readonly systemName: string} | {readonly materialSymbol: string};
+
+export type PlatformEntry<P extends NativePlatform> = Partial<
+  PlatformVocabulary[P]
+> & {
+  readonly minVersion?: string;
+  readonly maxVersion?: string;
+  /** Overrides for this platform's theme targets, keyed by target. */
+  readonly components?: Readonly<
+    Record<string, Readonly<Record<string, string | number>>>
+  >;
+  readonly icons?: Readonly<Record<string, PlatformIcon>>;
+};
+
+export interface NativeThemeConfig {
+  readonly material?: DurableMaterial;
+  readonly platforms?: {
+    readonly [P in NativePlatform]?: ReadonlyArray<PlatformEntry<P>>;
+  };
+}
+
+export interface NativeTheme {
+  readonly theme: PortableThemeLike;
+  readonly config: NativeThemeConfig;
+}
+
+export interface DefineNativeThemeOptions {
+  /** Native theme to extend: durable members merge, platform entry lists replace. */
+  readonly extends?: NativeTheme;
+  /** Receives each report; defaults to console.warn outside production. */
+  readonly onReport?: (message: string) => void;
+}
+
+/** Platform terms that exist only from a given OS version. */
+const FEATURE_FLOORS: Readonly<
+  Record<string, Readonly<Record<string, string>>>
+> = {
+  ios: {liquidGlass: '26'},
+  macos: {liquidGlass: '26'},
+  windows: {mica: '11'},
+};
+
+/** Web-only parts of a defined theme that have no native meaning (FR18). */
+const WEB_PARTS = [
+  'components',
+  'icons',
+  'indicators',
+  '__onDark',
+  '__onLight',
+  '__adaptations',
+];
+
+export function compareVersions(a: string, b: string): number {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const diff = (pa[i] ?? 0) - (pb[i] ?? 0);
+    if (diff !== 0) {
+      return diff;
+    }
+  }
+  return 0;
+}
+
+function hasContent(value: unknown): boolean {
+  if (value == null) {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return value.length > 0;
+  }
+  if (typeof value === 'object') {
+    return Object.keys(value).length > 0;
+  }
+  return true;
+}
+
+function validate(config: NativeThemeConfig): string[] {
+  const errors: string[] = [];
+  for (const platform of NATIVE_PLATFORMS) {
+    for (const entry of config.platforms?.[platform] ?? []) {
+      const material = (entry as {material?: string}).material;
+      const floor = material ? FEATURE_FLOORS[platform]?.[material] : undefined;
+      if (
+        floor &&
+        (entry.minVersion == null ||
+          compareVersions(entry.minVersion, floor) < 0)
+      ) {
+        errors.push(
+          `${platform} material "${material}" exists only from ${platform} ${floor}; ` +
+            `scope its entry with minVersion: '${floor}' or later`,
+        );
+      }
+      if (
+        entry.minVersion &&
+        entry.maxVersion &&
+        compareVersions(entry.minVersion, entry.maxVersion) > 0
+      ) {
+        errors.push(`${platform} entry has minVersion above maxVersion`);
+      }
+    }
+  }
+  return errors;
+}
+
+export function defineNativeTheme(
+  theme: PortableThemeLike,
+  config: NativeThemeConfig,
+  options: DefineNativeThemeOptions = {},
+): NativeTheme {
+  const merged: NativeThemeConfig = options.extends
+    ? {
+        ...options.extends.config,
+        ...config,
+        platforms: {...options.extends.config.platforms, ...config.platforms},
+      }
+    : config;
+
+  const errors = validate(merged);
+  if (errors.length > 0) {
+    throw new Error(`defineNativeTheme(${theme.name}): ${errors.join('; ')}`);
+  }
+
+  const report =
+    options.onReport ??
+    ((message: string) => {
+      const env =
+        typeof process === 'undefined' ? undefined : process.env?.NODE_ENV;
+      if (env !== 'production') {
+        console.warn(message);
+      }
+    });
+  const received = theme as unknown as Record<string, unknown>;
+  for (const part of WEB_PARTS) {
+    if (hasContent(received[part])) {
+      report(
+        `defineNativeTheme(${theme.name}): "${part.replace(/^__/, '')}" is web-only and has ` +
+          'no native meaning; use native platform entries instead',
+      );
+    }
+  }
+
+  const portable: PortableThemeLike = {
+    name: theme.name,
+    tokens: theme.tokens,
+    ...(theme.localTokens ? {localTokens: theme.localTokens} : {}),
+  };
+  return {theme: portable, config: merged};
+}
+
+export interface ResolvedNativeTheme {
+  readonly material?: string;
+  readonly components: Readonly<
+    Record<string, Readonly<Record<string, string | number>>>
+  >;
+  readonly icons: Readonly<Record<string, PlatformIcon>>;
+}
+
+/** Applies durable intent, then each matching platform entry in order. */
+export function resolveNativeTheme(
+  nativeTheme: NativeTheme,
+  target: {readonly platform: NativePlatform; readonly osVersion: string},
+): ResolvedNativeTheme {
+  let resolved: ResolvedNativeTheme = {
+    ...(nativeTheme.config.material
+      ? {material: nativeTheme.config.material}
+      : {}),
+    components: {},
+    icons: {},
+  };
+  const entries = (nativeTheme.config.platforms?.[target.platform] ??
+    []) as ReadonlyArray<PlatformEntry<NativePlatform>>;
+  for (const entry of entries) {
+    if (
+      entry.minVersion &&
+      compareVersions(target.osVersion, entry.minVersion) < 0
+    ) {
+      continue;
+    }
+    if (
+      entry.maxVersion &&
+      compareVersions(target.osVersion, entry.maxVersion) > 0
+    ) {
+      continue;
+    }
+    const {minVersion: _min, maxVersion: _max, ...members} = entry;
+    resolved = {...resolved, ...members};
+  }
+  return resolved;
+}