@astryxdesign/native 0.7.4-canary.720bb10 → 0.7.5-canary.04434e7

package/src/components/Badge.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file components/Badge.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core Badge contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Badge documentation
+ */
+
+import type {NativeAdditions} from '../contract/fromComponentDoc.js';
+
+export const badge: NativeAdditions = {
+  name: 'Badge',
+  baseTarget: 'root',
+  // `icon` stays web-only until the core has an icon slot.
+  slots: {label: 'text'},
+};

package/src/components/Button.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 const button: NativeAdditions = {
+  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/src/components/Card.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file components/Card.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core Card contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Card documentation
+ */
+
+import type {NativeAdditions} from '../contract/fromComponentDoc.js';
+
+export const card: NativeAdditions = {
+  name: 'Card',
+  baseTarget: 'container',
+  slots: {children: 'content'},
+  sameMeaning: {children: "the component's content, as on the web"},
+};

package/src/components/Divider.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 const divider: NativeAdditions = {
+  name: 'Divider',
+  baseTarget: 'root',
+  slots: {label: 'text'},
+};

package/src/components/HStack.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file components/HStack.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core HStack contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Stack documentation, which documents HStack
+ */
+
+import type {NativeAdditions} from '../contract/fromComponentDoc.js';
+import {STACK_SLOTS} from './stackShared.js';
+
+export const hStack: NativeAdditions = {
+  name: 'HStack',
+  baseTarget: 'container',
+  doc: {file: 'Stack', component: 'HStack'},
+  slots: STACK_SLOTS,
+  sameMeaning: {children: "the component's content, as on the web"},
+};

package/src/components/Heading.ts

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 const heading: NativeAdditions = {
+  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/src/components/ProgressBar.ts

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 const progressBar: NativeAdditions = {
+  name: 'ProgressBar',
+  baseTarget: 'root',
+};

package/src/components/Switch.ts

@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 const switchControl: NativeAdditions = {
+  name: 'Switch',
+  // The web Switch forwards base props to its root wrapper.
+  baseTarget: 'root',
+};

package/src/components/Text.ts

@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 const text: NativeAdditions = {
+  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/src/components/TextInput.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @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 const textInput: NativeAdditions = {
+  name: 'TextInput',
+  // family:input-fields routes base props to the primary semantic control.
+  baseTarget: 'control',
+  webOnly: {
+    autoComplete: 'HTML autocomplete attribute',
+  },
+};

package/src/components/VStack.ts

@@ -0,0 +1,20 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file components/VStack.ts
+ * @input None
+ * @output What @astryxdesign/native adds to the core VStack contract
+ * @position Native additions read by fromComponentDoc together with core's
+ *   Stack documentation, which documents VStack
+ */
+
+import type {NativeAdditions} from '../contract/fromComponentDoc.js';
+import {STACK_SLOTS} from './stackShared.js';
+
+export const vStack: NativeAdditions = {
+  name: 'VStack',
+  baseTarget: 'container',
+  doc: {file: 'Stack', component: 'VStack'},
+  slots: STACK_SLOTS,
+  sameMeaning: {children: "the component's content, as on the web"},
+};

package/src/components/index.ts

@@ -9,6 +9,30 @@
  */
 
 import type {NativeAdditions} from '../contract/fromComponentDoc.js';
+import {badge} from './Badge.js';
+import {button} from './Button.js';
+import {card} from './Card.js';
+import {divider} from './Divider.js';
+import {heading} from './Heading.js';
+import {hStack} from './HStack.js';
+import {progressBar} from './ProgressBar.js';
 import {selector} from './Selector.js';
+import {switchControl} from './Switch.js';
+import {text} from './Text.js';
+import {textInput} from './TextInput.js';
+import {vStack} from './VStack.js';
 
-export const NATIVE_COMPONENTS: readonly NativeAdditions[] = [selector];
+export const NATIVE_COMPONENTS: readonly NativeAdditions[] = [
+  badge,
+  button,
+  card,
+  divider,
+  heading,
+  hStack,
+  progressBar,
+  selector,
+  switchControl,
+  text,
+  textInput,
+  vStack,
+];

package/src/components/stackShared.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file components/stackShared.ts
+ * @input None
+ * @output The slot declarations HStack and VStack share
+ * @position Read by components/HStack.ts and components/VStack.ts
+ */
+
+import type {SlotKind} from '../contract/fromComponentDoc.js';
+
+export const STACK_SLOTS: Readonly<Record<string, SlotKind>> = {
+  children: 'content',
+};

package/src/contract/contracts.test.ts

@@ -51,6 +51,40 @@ describe('native contracts', () => {
     expect(selector!.core).not.toHaveProperty('controlXstyle');
   });
 
+  it('keeps value callbacks, typed text slots, and number sets in the core', async () => {
+    const {contracts} = await buildContracts(loadCoreDoc);
+    const byName = new Map(
+      contracts.map(contract => [contract.name, contract]),
+    );
+    expect(byName.get('Switch')!.core.onChange?.type).toEqual({
+      kind: 'fn',
+      args: [{kind: 'boolean'}],
+    });
+    expect(byName.get('TextInput')!.core.onChange?.type).toEqual({
+      kind: 'fn',
+      args: [{kind: 'string'}],
+    });
+    expect(byName.get('Button')!.core.onClick?.type).toEqual({
+      kind: 'fn',
+      args: [],
+    });
+    expect(byName.get('Heading')!.core.children?.type).toEqual({
+      kind: 'string',
+    });
+    expect(byName.get('Heading')!.core.level?.type).toEqual({
+      kind: 'numberEnum',
+      values: [1, 2, 3, 4, 5, 6],
+    });
+    expect(byName.get('Text')!.core).not.toHaveProperty('id');
+    expect(byName.get('Badge')!.core.label).toMatchObject({
+      type: {kind: 'string'},
+      optional: false,
+    });
+    expect(byName.get('Badge')!.webOnly.map(prop => prop.name)).toContain(
+      'icon',
+    );
+  });
+
   it('reports naming and portability errors', () => {
     const bad: ComponentContract = {
       name: 'Bad',
@@ -146,5 +180,29 @@ describe('native contracts', () => {
     expect(errorsFor(null, usage('pullDown')).join('\n')).toContain(
       'menuStyle',
     );
+
+    const wire = (node: string, action: string) =>
+      "import type {AstryxAction, AstryxNode} from '@astryxdesign/native/components';\n" +
+      `export const node: AstryxNode = ${node};\n` +
+      `export const action: AstryxAction = ${action};\n`;
+    const tree =
+      "{component: 'VStack', key: 'root', props: {gap: 2, children: [" +
+      "{component: 'Switch', key: 'wifi', props: {label: 'Wi-Fi', value: true}, events: ['onChange']}," +
+      "{component: 'Selector', key: 'ship', props: {label: 'Shipping', options: [], menuStyle: 'pullDown'}}]}}";
+    const toggled =
+      "{key: 'wifi', component: 'Switch', event: 'onChange', args: [false]}";
+    expect(errorsFor('ios', wire(tree, toggled))).toEqual([]);
+    expect(errorsFor('android', wire(tree, toggled)).join('\n')).toContain(
+      'pullDown',
+    );
+    expect(
+      errorsFor(
+        'ios',
+        wire(
+          tree,
+          "{key: 'wifi', component: 'Switch', event: 'onChange', args: ['off']}",
+        ),
+      ).length,
+    ).toBeGreaterThan(0);
   });
 });

package/src/contract/fromComponentDoc.test.ts

@@ -0,0 +1,97 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {fromComponentDoc, type ComponentDocLike} from './fromComponentDoc.js';
+import {generateSwift} from './generateSwift.js';
+
+const doc: ComponentDocLike = {
+  name: 'Toggle',
+  props: [
+    {name: 'label', type: 'ReactNode', required: true},
+    {name: 'icon', type: 'ReactNode'},
+    {name: 'level', type: '1 | 2 | 3'},
+    {
+      name: 'onChange',
+      type: '(on: boolean, e: ChangeEvent<HTMLInputElement>) => void',
+    },
+    {name: 'onClick', type: '(e: MouseEvent) => void'},
+    {name: 'onFocus', type: '(e: FocusEvent) => void'},
+    {name: 'onPick', type: '(e: MouseEvent, value: string) => void'},
+  ],
+};
+
+describe('fromComponentDoc', () => {
+  const contract = fromComponentDoc(doc, {
+    name: 'Toggle',
+    baseTarget: 'control',
+    slots: {label: 'text'},
+    callbacks: ['onClick', 'onPick'],
+    sameMeaning: {onClick: 'a press in Compose too'},
+  });
+
+  it('gives declared content a typed text slot and leaves the rest on the web', () => {
+    expect(contract.core.label).toEqual({
+      type: {kind: 'string'},
+      optional: false,
+    });
+    expect(contract.webOnly.map(prop => prop.name)).toContain('icon');
+  });
+
+  it('keeps a value callback and a declared press, and leaves other event callbacks on the web', () => {
+    expect(contract.core.onChange?.type).toEqual({
+      kind: 'fn',
+      args: [{kind: 'boolean'}],
+    });
+    expect(contract.core.onClick?.type).toEqual({kind: 'fn', args: []});
+    expect(contract.webOnly).toContainEqual({
+      name: 'onFocus',
+      reason: 'callback argument: DOM event',
+    });
+    // `callbacks` never drops values: an event before a value stays on the web.
+    expect(contract.core).not.toHaveProperty('onPick');
+    expect(contract.webOnly.map(prop => prop.name)).toContain('onPick');
+  });
+
+  it('refuses a toolkit name unless the component declares the same meaning', () => {
+    const plain = fromComponentDoc(doc, {
+      name: 'Toggle',
+      baseTarget: 'control',
+      callbacks: ['onClick'],
+    });
+    expect(plain.core).not.toHaveProperty('onClick');
+    expect(
+      plain.webOnly.find(prop => prop.name === 'onClick')?.reason,
+    ).toContain('compose');
+  });
+
+  it('writes a closed set of numbers as a Swift enum with raw values', () => {
+    const swift = generateSwift([contract])['Toggle.swift'];
+    expect(swift).toContain(
+      'public enum ToggleLevel: Int, CaseIterable, Codable, Sendable {',
+    );
+    expect(swift).toContain('  case v1 = 1');
+  });
+
+  it('reads one component of a file that documents several', () => {
+    const stack: ComponentDocLike = {
+      name: 'Stack',
+      components: [
+        {name: 'Stack', props: [{name: 'gap', type: '0 | 0.5 | 1'}]},
+        {name: 'VStack', props: [{name: 'wrap', type: 'boolean'}]},
+      ],
+    };
+    const vstack = fromComponentDoc(stack, {
+      name: 'VStack',
+      baseTarget: 'container',
+      doc: {file: 'Stack', component: 'VStack'},
+    });
+    expect(Object.keys(vstack.core)).toEqual(['wrap']);
+    expect(() =>
+      fromComponentDoc(stack, {
+        name: 'Missing',
+        baseTarget: 'root',
+        doc: {file: 'Stack', component: 'Missing'},
+      }),
+    ).toThrow('does not document "Missing"');
+  });
+});

package/src/contract/fromComponentDoc.ts

@@ -17,25 +17,63 @@ import type {
   ComponentContract,
   PropMap,
   PropSpec,
+  PropType,
   WebOnlyProp,
 } 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;
+ * `content` is child Astryx components, as a stack's or a card's children.
+ */
+export type SlotKind = 'text' | 'content';
+
 /** 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.
@@ -51,6 +89,29 @@ export interface NativeAdditions {
   readonly webOnly?: Readonly<Record<string, string>>;
 }
 
+/** The documented props of the component the additions name. */
+function documentedProps(
+  doc: ComponentDocLike,
+  additions: NativeAdditions,
+): ReadonlyArray<DocProp> {
+  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: Readonly<Record<SlotKind, PropType>> = {
+  text: {kind: 'string'},
+  content: {kind: 'content'},
+};
+
 export function fromComponentDoc(
   doc: ComponentDocLike,
   additions: NativeAdditions,
@@ -58,8 +119,15 @@ export function fromComponentDoc(
   const core: Record<string, PropSpec> = {};
   const webOnly: WebOnlyProp[] = [];
   const types = additions.types ?? {};
+  const describe = (prop: DocProp) =>
+    typeof prop.description === 'string' ? {doc: prop.description} : {};
 
-  for (const prop of doc.props ?? []) {
+  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});
@@ -76,13 +144,39 @@ export function fromComponentDoc(
       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;
@@ -116,7 +210,7 @@ export function fromComponentDoc(
     core[prop.name] = {
       type,
       optional: prop.required !== true,
-      ...(typeof prop.description === 'string' ? {doc: prop.description} : {}),
+      ...describe(prop),
     };
   }
 
@@ -127,5 +221,8 @@ export function fromComponentDoc(
     core,
     platforms: additions.platforms ?? {},
     webOnly,
+    sameMeaning: Object.keys(additions.sameMeaning ?? {}).filter(
+      name => name in core,
+    ),
   };
 }