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

package/dist/contract/generateSwift.js

@@ -0,0 +1,133 @@
+// 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';
+const HEADER = '// Generated by @astryxdesign/native. Do not edit.\n';
+const APPLE_PLATFORMS = [
+    { platform: 'ios', condition: 'os(iOS)' },
+    { platform: 'macos', condition: 'os(macOS)' },
+];
+const camel = (text) => text.replace(/[-_ ]+([a-zA-Z0-9])/g, (_, ch) => ch.toUpperCase());
+const pascal = (text) => camel(text).replace(/^./, ch => ch.toUpperCase());
+const ident = (name) => SWIFT_KEYWORDS.has(name) ? `\`${name}\`` : name;
+function caseName(value) {
+    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 {
+    decls = [];
+    type(owner, prop, type) {
+        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, props) {
+        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, props, conformances, extra = []) {
+        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) {
+    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) {
+    const files = { 'AstryxBase.swift': BASE_FILE };
+    for (const contract of contracts) {
+        files[`${contract.name}.swift`] = componentFile(contract);
+    }
+    return files;
+}

package/dist/contract/generateTypeScript.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentContract } from './types.js';
+/** Returns file name to contents, relative to the types output folder. */
+export declare function generateTypeScript(contracts: readonly ComponentContract[]): Record<string, string>;
+//# sourceMappingURL=generateTypeScript.d.ts.map

package/dist/contract/generateTypeScript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateTypeScript.d.ts","sourceRoot":"","sources":["../../src/contract/generateTypeScript.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAC,iBAAiB,EAAoB,MAAM,YAAY,CAAC;AA2FrE,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,iBAAiB,EAAE,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASxB"}

package/dist/contract/generateTypeScript.js

@@ -0,0 +1,87 @@
+// 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 } from '../platforms.js';
+const HEADER = '// Generated by @astryxdesign/native. Do not edit.\n';
+function tsType(type) {
+    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) {
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : `'${name}'`;
+}
+function members(props, separator = '\n  ') {
+    return Object.entries(props)
+        .map(([name, spec]) => `${key(name)}${spec.optional ? '?' : ''}: ${tsType(spec.type)};`)
+        .join(separator);
+}
+function coreFile(contracts) {
+    const types = new Map();
+    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) {
+    const names = new Set(['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, platform) {
+    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) {
+    const files = {
+        '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/dist/contract/index.d.ts

@@ -0,0 +1,20 @@
+import { type ComponentDocLike } from './fromComponentDoc.js';
+import { 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 declare function buildContracts(loadDoc: ComponentDocLoader): Promise<BuiltContracts>;
+//# sourceMappingURL=index.d.ts.map

package/dist/contract/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contract/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAmB,KAAK,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AAC9E,OAAO,EAAgB,KAAK,aAAa,EAAC,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,YAAY,CAAC;AAElD,OAAO,EAAC,gBAAgB,EAAC,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAC,gBAAgB,EAAE,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAC7E,OAAO,EAAC,aAAa,EAAC,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAC,kBAAkB,EAAC,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAC,YAAY,EAAC,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAC,aAAa,EAAE,eAAe,EAAC,MAAM,YAAY,CAAC;AAC1D,YAAY,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAC9C,mBAAmB,YAAY,CAAC;AAEhC,kEAAkE;AAClE,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;AAE7E,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC7C;AAED,8EAA8E;AAC9E,wBAAsB,cAAc,CAClC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC,CAiBzB"}

package/dist/contract/index.js

@@ -0,0 +1,33 @@
+// 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 } from './fromComponentDoc.js';
+import { checkContract } from './rules.js';
+export { fromComponentDoc } from './fromComponentDoc.js';
+export { generateSwift } from './generateSwift.js';
+export { generateTypeScript } from './generateTypeScript.js';
+export { parseDocType } from './parseDocType.js';
+export { checkContract, coreNameProblem } from './rules.js';
+/** Builds and checks every native component contract; throws on any error. */
+export async function buildContracts(loadDoc) {
+    const contracts = [];
+    const warnings = [];
+    const errors = [];
+    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/dist/contract/names.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @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 declare const SWIFT_KEYWORDS: ReadonlySet<string>;
+export declare const KOTLIN_KEYWORDS: ReadonlySet<string>;
+/**
+ * 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 declare const TOOLKIT_NAMES: Readonly<Record<string, ReadonlySet<string>>>;
+/**
+ * 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 declare const RECLAIMED: ReadonlySet<string>;
+//# sourceMappingURL=names.d.ts.map

package/dist/contract/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../../src/contract/names.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAQ9C,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAK/C,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CA4DvE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,WAAW,CAAC,MAAM,CAKxC,CAAC"}

package/dist/contract/names.js

@@ -0,0 +1,90 @@
+// 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 = 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 = 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 = {
+    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 = new Set([
+    'onChange',
+    'title',
+    'color',
+    'content',
+]);

package/dist/contract/parseDocType.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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 { PropType } from './types.js';
+export type ParsedType = {
+    readonly ok: true;
+    readonly type: PropType;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * 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 declare function parseDocType(raw: string): ParsedType;
+//# sourceMappingURL=parseDocType.d.ts.map

package/dist/contract/parseDocType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseDocType.d.ts","sourceRoot":"","sources":["../../src/contract/parseDocType.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,KAAK,EAAW,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEnD,MAAM,MAAM,UAAU,GAClB;IAAC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAC,GAC5C;IAAC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAAC;AAuIlD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAwDpD"}

package/dist/contract/parseDocType.js

@@ -0,0 +1,183 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** Web-only types, keyed by name, with the reason each has no native form. */
+const WEB_ONLY_TYPES = {
+    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) => ({ ok: true, type });
+const no = (reason) => ({ ok: false, reason });
+/** Splits on a separator at bracket depth zero, ignoring quoted text. */
+function splitTop(text, separator) {
+    const parts = [];
+    let depth = 0;
+    let quote = 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) {
+    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) {
+    let t = text.trim();
+    while (isWrappedInParens(t)) {
+        t = t.slice(1, -1).trim();
+    }
+    return t;
+}
+function parseRecord(body) {
+    const fields = {};
+    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) {
+    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 = [];
+    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) {
+    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/dist/contract/rules.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentContract } 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 declare function coreNameProblem(name: string): string | null;
+export declare function checkContract(contract: ComponentContract): ContractIssue[];
+//# sourceMappingURL=rules.d.ts.map

package/dist/contract/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../../src/contract/rules.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAC,iBAAiB,EAAoB,MAAM,YAAY,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,IAAI,EACT,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,uBAAuB,GACvB,6BAA6B,GAC7B,cAAc,CAAC;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgB3D;AAeD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,aAAa,EAAE,CAoE1E"}