@astryxdesign/native 0.7.5-canary.f2dafed → 0.7.5-canary.fccd771

package/apple/Tests/AstryxNativeTests/ControlPropsTests.swift

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import Testing
+@testable import AstryxNative
+
+@Test func valueCallbacksCarryTheValueOnly() {
+  var received: Bool?
+  let props = SwitchProps(label: "Wi-Fi", value: false, onChange: { received = $0 })
+  props.onChange?(true)
+  #expect(received == true)
+  #expect(SwitchProps.baseTarget == .root)
+}
+
+@Test func textSlotsAndNumberSetsAreTyped() {
+  let heading = HeadingProps(level: .v2, children: "Orders")
+  #expect(heading.level.rawValue == 2)
+  #expect(heading.children == "Orders")
+  let divider = DividerProps(label: "Or")
+  #expect(divider.label == "Or")
+}
+
+@Test func aButtonPressTakesNoArguments() {
+  var pressed = 0
+  let button = ButtonProps(label: "Pay", onClick: { pressed += 1 })
+  button.onClick?()
+  #expect(pressed == 1)
+}

package/dist/components/Button.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file components/Button.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core Button contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Button documentation
+ */
+import type { NativeAdditions } from '../contract/fromComponentDoc.js';
+export declare const button: NativeAdditions;
+//# sourceMappingURL=Button.d.ts.map

package/dist/components/Button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.d.ts","sourceRoot":"","sources":["../../src/components/Button.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE,eAAO,MAAM,MAAM,EAAE,eAapB,CAAC"}

package/dist/components/Button.js

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+export const button = {
+    name: 'Button',
+    baseTarget: 'root',
+    callbacks: ['onClick'],
+    sameMeaning: { onClick: 'a press, as in Compose' },
+    webOnly: {
+        type: 'HTML form submission type',
+        name: 'HTML form field name',
+        form: 'HTML form owner',
+        target: 'HTML link target',
+        rel: 'HTML link relationship',
+        isIconOnly: 'needs an icon, which has no core slot yet',
+    },
+};

package/dist/components/Divider.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file components/Divider.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core Divider contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Divider documentation
+ */
+import type { NativeAdditions } from '../contract/fromComponentDoc.js';
+export declare const divider: NativeAdditions;
+//# sourceMappingURL=Divider.d.ts.map

package/dist/components/Divider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Divider.d.ts","sourceRoot":"","sources":["../../src/components/Divider.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE,eAAO,MAAM,OAAO,EAAE,eAIrB,CAAC"}

package/dist/components/Divider.js

@@ -0,0 +1,6 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+export const divider = {
+    name: 'Divider',
+    baseTarget: 'root',
+    slots: { label: 'text' },
+};

package/dist/components/Heading.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file components/Heading.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core Heading contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Heading documentation
+ */
+import type { NativeAdditions } from '../contract/fromComponentDoc.js';
+export declare const heading: NativeAdditions;
+//# sourceMappingURL=Heading.d.ts.map

package/dist/components/Heading.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Heading.d.ts","sourceRoot":"","sources":["../../src/components/Heading.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE,eAAO,MAAM,OAAO,EAAE,eAYrB,CAAC"}

package/dist/components/Heading.js

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+export const heading = {
+    name: 'Heading',
+    baseTarget: 'root',
+    doc: { file: 'Text/Heading' },
+    slots: { children: 'text' },
+    sameMeaning: { children: "the component's content, as on the web" },
+    webOnly: {
+        display: 'CSS display; native layout places text by its container',
+        wordBreak: 'CSS line breaking; native text breaks by platform rules',
+        textWrap: 'CSS text wrapping; native text wraps by platform rules',
+        hasCapsize: 'web text-box trimming of CSS line height',
+    },
+};

package/dist/components/ProgressBar.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file components/ProgressBar.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core ProgressBar contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   ProgressBar documentation
+ */
+import type { NativeAdditions } from '../contract/fromComponentDoc.js';
+export declare const progressBar: NativeAdditions;
+//# sourceMappingURL=ProgressBar.d.ts.map

package/dist/components/ProgressBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProgressBar.d.ts","sourceRoot":"","sources":["../../src/components/ProgressBar.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE,eAAO,MAAM,WAAW,EAAE,eAGzB,CAAC"}

package/dist/components/ProgressBar.js

@@ -0,0 +1,5 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+export const progressBar = {
+    name: 'ProgressBar',
+    baseTarget: 'root',
+};

package/dist/components/Switch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file components/Switch.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core Switch contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Switch documentation
+ */
+import type { NativeAdditions } from '../contract/fromComponentDoc.js';
+export declare const switchControl: NativeAdditions;
+//# sourceMappingURL=Switch.d.ts.map

package/dist/components/Switch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Switch.d.ts","sourceRoot":"","sources":["../../src/components/Switch.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE,eAAO,MAAM,aAAa,EAAE,eAI3B,CAAC"}

package/dist/components/Switch.js

@@ -0,0 +1,6 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+export const switchControl = {
+    name: 'Switch',
+    // The web Switch forwards base props to its root wrapper.
+    baseTarget: 'root',
+};

package/dist/components/Text.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file components/Text.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core Text contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Text documentation
+ */
+import type { NativeAdditions } from '../contract/fromComponentDoc.js';
+export declare const text: NativeAdditions;
+//# sourceMappingURL=Text.d.ts.map

package/dist/components/Text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Text.d.ts","sourceRoot":"","sources":["../../src/components/Text.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE,eAAO,MAAM,IAAI,EAAE,eAWlB,CAAC"}

package/dist/components/Text.js

@@ -0,0 +1,13 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+export const text = {
+    name: 'Text',
+    baseTarget: 'root',
+    slots: { children: 'text' },
+    sameMeaning: { children: "the component's content, as on the web" },
+    webOnly: {
+        display: 'CSS display; native layout places text by its container',
+        wordBreak: 'CSS line breaking; native text breaks by platform rules',
+        textWrap: 'CSS text wrapping; native text wraps by platform rules',
+        hasCapsize: 'web text-box trimming of CSS line height',
+    },
+};

package/dist/components/TextInput.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @file components/TextInput.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core TextInput contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   TextInput documentation
+ */
+import type { NativeAdditions } from '../contract/fromComponentDoc.js';
+export declare const textInput: NativeAdditions;
+//# sourceMappingURL=TextInput.d.ts.map

package/dist/components/TextInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TextInput.d.ts","sourceRoot":"","sources":["../../src/components/TextInput.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE,eAAO,MAAM,SAAS,EAAE,eAOvB,CAAC"}

package/dist/components/TextInput.js

@@ -0,0 +1,9 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+export const textInput = {
+    name: 'TextInput',
+    // family:input-fields routes base props to the primary semantic control.
+    baseTarget: 'control',
+    webOnly: {
+        autoComplete: 'HTML autocomplete attribute',
+    },
+};

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAGrE,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAUrE,eAAO,MAAM,iBAAiB,EAAE,SAAS,eAAe,EASvD,CAAC"}

package/dist/components/index.js

@@ -1,3 +1,19 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+import { button } from './Button.js';
+import { divider } from './Divider.js';
+import { heading } from './Heading.js';
+import { progressBar } from './ProgressBar.js';
 import { selector } from './Selector.js';
-export const NATIVE_COMPONENTS = [selector];
+import { switchControl } from './Switch.js';
+import { text } from './Text.js';
+import { textInput } from './TextInput.js';
+export const NATIVE_COMPONENTS = [
+    button,
+    divider,
+    heading,
+    progressBar,
+    selector,
+    switchControl,
+    text,
+    textInput,
+];

package/dist/contract/fromComponentDoc.d.ts

@@ -1,19 +1,56 @@
 import type { BaseTarget, ComponentContract, PropMap } from './types.js';
 import type { NativePlatform } from '../platforms.js';
-/** The subset of a ComponentDoc this reader needs. */
+interface DocProp {
+    readonly name: string;
+    readonly type?: unknown;
+    readonly required?: boolean;
+    readonly description?: unknown;
+}
+/**
+ * The subset of a ComponentDoc this reader needs. A file that documents
+ * several components, such as Stack with HStack and VStack, lists them in
+ * `components`.
+ */
 export interface ComponentDocLike {
     readonly name: string;
-    readonly props?: ReadonlyArray<{
+    readonly props?: ReadonlyArray<DocProp>;
+    readonly components?: ReadonlyArray<{
         readonly name: string;
-        readonly type?: unknown;
-        readonly required?: boolean;
-        readonly description?: unknown;
+        readonly props?: ReadonlyArray<DocProp>;
     }>;
 }
+/**
+ * Typed slots (AST-082 FR4) for documented free-form content. `text` is a
+ * string in the core contract, as a badge's label or a heading's words.
+ */
+export type SlotKind = 'text';
 /** What the native package adds to one core component. */
 export interface NativeAdditions {
     readonly name: string;
     readonly baseTarget: BaseTarget;
+    /**
+     * Where core documents the component when it is not `<Name>/<Name>.doc.mjs`:
+     * `file` relative to core's `src` without `.doc.mjs`, and `component` when
+     * the file documents several components.
+     */
+    readonly doc?: {
+        readonly file: string;
+        readonly component?: string;
+    };
+    /** Documented free-form content props, given a typed slot in the core. */
+    readonly slots?: Readonly<Record<string, SlotKind>>;
+    /**
+     * Callbacks whose only documented argument is a DOM event but which name a
+     * moment every platform has, such as a button's press. Their core form
+     * takes no arguments.
+     */
+    readonly callbacks?: readonly string[];
+    /**
+     * Core props whose name a platform toolkit also uses, with the same meaning
+     * (AST-082 FR8 forbids only a different meaning), and why: a button's
+     * `onClick` is a press in Compose too.
+     */
+    readonly sameMeaning?: Readonly<Record<string, string>>;
     /**
      * Portable definitions for named types the documentation references. Fields
      * the web type has that are not portable are left out on purpose.
@@ -29,4 +66,5 @@ export interface NativeAdditions {
     readonly webOnly?: Readonly<Record<string, string>>;
 }
 export declare function fromComponentDoc(doc: ComponentDocLike, additions: NativeAdditions): ComponentContract;
+export {};
 //# sourceMappingURL=fromComponentDoc.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"fromComponentDoc.d.ts","sourceRoot":"","sources":["../../src/contract/fromComponentDoc.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,OAAO,EAGR,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAEpD,sDAAsD;AACtD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC,CAAC;CACJ;AAED,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACxE;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,eAAe,GACzB,iBAAiB,CA0EnB"}
+{"version":3,"file":"fromComponentDoc.d.ts","sourceRoot":"","sources":["../../src/contract/fromComponentDoc.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EACjB,OAAO,EAIR,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,iBAAiB,CAAC;AAEpD,UAAU,OAAO;IACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;QAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;KACzC,CAAC,CAAC;CACJ;AAED;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAC,CAAC;IACpE,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IACpD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACxE;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAwBD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,eAAe,GACzB,iBAAiB,CA8GnB"}

package/dist/contract/fromComponentDoc.js

@@ -10,11 +10,32 @@
  */
 import { parseDocType } from './parseDocType.js';
 import { coreNameProblem } from './rules.js';
+/** The documented props of the component the additions name. */
+function documentedProps(doc, additions) {
+    const wanted = additions.doc?.component;
+    if (wanted == null) {
+        return doc.props ?? [];
+    }
+    const entry = doc.components?.find(component => component.name === wanted);
+    if (!entry) {
+        throw new Error(`${additions.name}: core documentation "${doc.name}" does not document "${wanted}"`);
+    }
+    return entry.props ?? [];
+}
+const SLOT_TYPES = {
+    text: { kind: 'string' },
+};
 export function fromComponentDoc(doc, additions) {
     const core = {};
     const webOnly = [];
     const types = additions.types ?? {};
-    for (const prop of doc.props ?? []) {
+    const describe = (prop) => typeof prop.description === 'string' ? { doc: prop.description } : {};
+    for (const prop of documentedProps(doc, additions)) {
+        // `id` and `isHidden` are shared base props on every platform (FR7), so a
+        // documented prop of either name is the base prop, not a core prop.
+        if (prop.name === 'id' || prop.name === 'isHidden') {
+            continue;
+        }
         const declaredWebOnly = additions.webOnly?.[prop.name];
         if (declaredWebOnly) {
             webOnly.push({ name: prop.name, reason: declaredWebOnly });
@@ -29,13 +50,33 @@ export function fromComponentDoc(doc, additions) {
             webOnly.push({ name: prop.name, reason: 'HTML attribute' });
             continue;
         }
-        const parsed = parseDocType(String(prop.type ?? ''));
+        const slot = additions.slots?.[prop.name];
+        const slotNameProblem = slot &&
+            coreNameProblem(prop.name, prop.name in (additions.sameMeaning ?? {}));
+        if (slotNameProblem) {
+            webOnly.push({ name: prop.name, reason: slotNameProblem });
+            continue;
+        }
+        if (slot) {
+            core[prop.name] = {
+                type: SLOT_TYPES[slot],
+                optional: prop.required !== true,
+                ...describe(prop),
+            };
+            continue;
+        }
+        let parsed = parseDocType(String(prop.type ?? ''));
+        if (!parsed.ok &&
+            parsed.eventOnly === true &&
+            additions.callbacks?.includes(prop.name)) {
+            parsed = { ok: true, type: { kind: 'fn', args: [] } };
+        }
         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);
+        const nameProblem = coreNameProblem(prop.name, prop.name in (additions.sameMeaning ?? {}));
         if (nameProblem) {
             webOnly.push({ name: prop.name, reason: nameProblem });
             continue;
@@ -67,7 +108,7 @@ export function fromComponentDoc(doc, additions) {
         core[prop.name] = {
             type,
             optional: prop.required !== true,
-            ...(typeof prop.description === 'string' ? { doc: prop.description } : {}),
+            ...describe(prop),
         };
     }
     return {
@@ -77,5 +118,6 @@ export function fromComponentDoc(doc, additions) {
         core,
         platforms: additions.platforms ?? {},
         webOnly,
+        sameMeaning: Object.keys(additions.sameMeaning ?? {}).filter(name => name in core),
     };
 }

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

@@ -1 +1 @@
-{"version":3,"file":"generateSwift.d.ts","sourceRoot":"","sources":["../../src/contract/generateSwift.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,iBAAiB,EAAoB,MAAM,YAAY,CAAC;AAoJrE,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,iBAAiB,EAAE,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB"}
+{"version":3,"file":"generateSwift.d.ts","sourceRoot":"","sources":["../../src/contract/generateSwift.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAC,iBAAiB,EAAoB,MAAM,YAAY,CAAC;AAoKrE,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,SAAS,EAAE,SAAS,iBAAiB,EAAE,GACtC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB"}

package/dist/contract/generateSwift.js

@@ -16,6 +16,10 @@ const APPLE_PLATFORMS = [
 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;
+/** `1` → `v1`, `0.5` → `v0_5`, `-1` → `vMinus1`. */
+function numberCaseName(value) {
+    return `v${String(value).replace('-', 'Minus').replace('.', '_')}`;
+}
 function caseName(value) {
     const name = camel(value.replace(/[^A-Za-z0-9_-]/g, '-'));
     return ident(/^[0-9]/.test(name) ? `v${name}` : name || 'empty');
@@ -37,6 +41,13 @@ class SwiftWriter {
                 this.decls.push(`public enum ${name}: String, CaseIterable, Sendable {\n${cases.join('\n')}\n}`);
                 return name;
             }
+            case 'numberEnum': {
+                const name = `${owner}${pascal(prop)}`;
+                const raw = type.values.every(Number.isInteger) ? 'Int' : 'Double';
+                const cases = type.values.map(value => `  case ${numberCaseName(value)} = ${value}`);
+                this.decls.push(`public enum ${name}: ${raw}, CaseIterable, Sendable {\n${cases.join('\n')}\n}`);
+                return name;
+            }
             case 'array':
                 return `[${this.type(owner, prop, type.of)}]`;
             case 'record': {

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

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

package/dist/contract/generateTypeScript.js

@@ -16,6 +16,8 @@ function tsType(type) {
             return type.kind;
         case 'enum':
             return type.values.map(value => `'${value}'`).join(' | ');
+        case 'numberEnum':
+            return type.values.join(' | ');
         case 'array': {
             const inner = tsType(type.of);
             return `ReadonlyArray<${inner}>`;

package/dist/contract/index.d.ts

@@ -2,15 +2,19 @@ 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 type { ComponentDocLike, NativeAdditions, SlotKind, } 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>;
+/**
+ * Loads one core documentation file: a component name for
+ * `<Name>/<Name>.doc.mjs`, or a path such as `Text/Heading` relative to core's
+ * `src` without `.doc.mjs`.
+ */
+export type ComponentDocLoader = (file: string) => Promise<ComponentDocLike>;
 export interface BuiltContracts {
     readonly contracts: readonly ComponentContract[];
     readonly warnings: readonly ContractIssue[];

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

@@ -1 +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"}
+{"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,EACV,gBAAgB,EAChB,eAAe,EACf,QAAQ,GACT,MAAM,uBAAuB,CAAC;AAC/B,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;;;;GAIG;AACH,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,CAkBzB"}

package/dist/contract/index.js

@@ -20,7 +20,8 @@ export async function buildContracts(loadDoc) {
     const warnings = [];
     const errors = [];
     for (const additions of NATIVE_COMPONENTS) {
-        const contract = fromComponentDoc(await loadDoc(additions.name), additions);
+        const doc = await loadDoc(additions.doc?.file ?? additions.name);
+        const contract = fromComponentDoc(doc, additions);
         for (const issue of checkContract(contract)) {
             (issue.level === 'error' ? errors : warnings).push(issue);
         }

package/dist/contract/parseDocType.d.ts

@@ -11,11 +11,14 @@ export type ParsedType = {
 } | {
     readonly ok: false;
     readonly reason: string;
+    /** True for a callback whose only arguments are DOM events. */
+    readonly eventOnly?: boolean;
 };
 /**
  * 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
+ * `number`, `boolean`, closed string or number unions, arrays, plain object
+ * literals, callbacks with portable arguments (a trailing DOM event argument
+ * is the web's part), and named types. A union of different
  * kinds has no Swift or Kotlin form.
  */
 export declare function parseDocType(raw: string): ParsedType;

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

@@ -1 +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"}
+{"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;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B,CAAC;AA8JN;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CA8DpD"}

package/dist/contract/parseDocType.js

@@ -19,7 +19,15 @@ const WEB_ONLY_TYPES = {
     ChangeEvent: 'DOM event',
     DragEvent: 'DOM event',
     ClipboardEvent: 'DOM event',
+    FormEvent: 'DOM event',
+    TouchEvent: 'DOM event',
+    SyntheticEvent: 'DOM event',
 };
+/** True for a DOM event type, with or without its element parameter. */
+function isDomEvent(text) {
+    const name = /^(?:React\.)?([A-Z]\w*)(?:<[\s\S]*>)?$/.exec(text.trim())?.[1];
+    return name != null && WEB_ONLY_TYPES[name] === '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. */
@@ -115,10 +123,24 @@ function parseFunction(text) {
             : '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 types = (params ? splitTop(params, ',') : []).map(param => {
         const match = /^([A-Za-z_$][\w$]*)\??\s*:\s*([\s\S]+)$/.exec(param);
-        const parsed = parseDocType(match ? match[2] : param);
+        return match ? match[2] : param;
+    });
+    // A value callback ends with the DOM event that caused it, as in
+    // `(checked: boolean, e: ChangeEvent) => void`. The values are the portable
+    // callback; the trailing event is the web's part. A callback that carries
+    // only an event stays on the web.
+    let end = types.length;
+    while (end > 0 && isDomEvent(types[end - 1])) {
+        end--;
+    }
+    if (end === 0 && types.length > 0) {
+        return { ok: false, reason: 'callback argument: DOM event', eventOnly: true };
+    }
+    const args = [];
+    for (const type of types.slice(0, end)) {
+        const parsed = parseDocType(type);
         if (!parsed.ok) {
             return no(`callback argument: ${parsed.reason}`);
         }
@@ -128,8 +150,9 @@ function parseFunction(text) {
 }
 /**
  * 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
+ * `number`, `boolean`, closed string or number unions, arrays, plain object
+ * literals, callbacks with portable arguments (a trailing DOM event argument
+ * is the web's part), and named types. A union of different
  * kinds has no Swift or Kotlin form.
  */
 export function parseDocType(raw) {
@@ -146,6 +169,9 @@ export function parseDocType(raw) {
         if (members.every(m => /^'[^']*'$/.test(m))) {
             return ok({ kind: 'enum', values: members.map(m => m.slice(1, -1)) });
         }
+        if (members.every(m => /^-?\d+(?:\.\d+)?$/.test(m))) {
+            return ok({ kind: 'numberEnum', values: members.map(Number) });
+        }
         const webOnly = members.find(m => WEB_ONLY_TYPES[m] != null);
         if (webOnly) {
             return no(WEB_ONLY_TYPES[webOnly]);
@@ -162,6 +188,9 @@ export function parseDocType(raw) {
     if (WEB_ONLY_TYPES[t] != null) {
         return no(WEB_ONLY_TYPES[t]);
     }
+    if (isDomEvent(t)) {
+        return no('DOM event');
+    }
     const generic = /^(?:Readonly)?Array<([\s\S]+)>$/.exec(t);
     if (t.endsWith('[]') || generic) {
         const inner = parseDocType(generic ? generic[1] : t.slice(0, -2));

package/dist/contract/rules.d.ts

@@ -4,7 +4,10 @@ export interface ContractIssue {
     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;
+/**
+ * Why a core prop name is not allowed, or null when it is. A toolkit name is
+ * allowed when the component declares it has the same meaning there.
+ */
+export declare function coreNameProblem(name: string, sameMeaning?: boolean): string | null;
 export declare function checkContract(contract: ComponentContract): ContractIssue[];
 //# sourceMappingURL=rules.d.ts.map

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

@@ -1 +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"}
+{"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;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,WAAW,UAAQ,GAClB,MAAM,GAAG,IAAI,CAgBf;AAeD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,aAAa,EAAE,CAqE1E"}