@agent-native/core 0.117.2 → 0.118.0

package/corpus/toolkit/src/conformance/types.ts

@@ -0,0 +1,45 @@
+import type { DesignSystemComponents } from "../design-system/types.js";
+
+export type DesignSystemConformanceCategory =
+  | "contract"
+  | "leaf"
+  | "behavior"
+  | "overlay-interoperability";
+
+export interface DesignSystemConformanceCheckResult {
+  id: string;
+  category: DesignSystemConformanceCategory;
+  components: readonly (keyof DesignSystemComponents)[];
+  passed: boolean;
+  message?: string;
+}
+
+export interface DesignSystemConformanceReport {
+  contractVersion: number;
+  adapterName: string;
+  passed: boolean;
+  results: readonly DesignSystemConformanceCheckResult[];
+}
+
+export interface RunDesignSystemConformanceOptions {
+  adapterName?: string;
+  components: DesignSystemComponents;
+  contractVersion: number;
+  document?: Document;
+}
+
+export class DesignSystemConformanceError extends Error {
+  readonly report: DesignSystemConformanceReport;
+
+  constructor(report: DesignSystemConformanceReport) {
+    const failures = report.results
+      .filter((result) => !result.passed)
+      .map((result) => `${result.id}: ${result.message ?? "failed"}`)
+      .join("\n");
+    super(
+      `Design system conformance failed for ${report.adapterName}:\n${failures}`,
+    );
+    this.name = "DesignSystemConformanceError";
+    this.report = report;
+  }
+}

package/corpus/toolkit/src/conformance/version.ts

@@ -0,0 +1,22 @@
+import { DESIGN_SYSTEM_CONTRACT_VERSION } from "../design-system/types.js";
+
+export const DESIGN_SYSTEM_CONTRACT_EVOLUTION_POLICY = {
+  minor: "New components and optional props are backward-compatible.",
+  major:
+    "Required props, removed components or props, and behavioral contract changes require a new contract major.",
+} as const;
+
+export function assertDesignSystemContractVersion(
+  adapterContractVersion: number,
+): void {
+  if (!Number.isInteger(adapterContractVersion) || adapterContractVersion < 1) {
+    throw new TypeError(
+      "Design system contractVersion must be a positive integer.",
+    );
+  }
+  if (adapterContractVersion !== DESIGN_SYSTEM_CONTRACT_VERSION) {
+    throw new RangeError(
+      `Design system contract major ${adapterContractVersion} is incompatible with Toolkit contract major ${DESIGN_SYSTEM_CONTRACT_VERSION}.`,
+    );
+  }
+}

package/corpus/toolkit/src/design-system/components.tsx

@@ -0,0 +1,146 @@
+import type { ComponentType } from "react";
+
+import { useDesignSystemComponent } from "./context.js";
+import { defaultDesignSystemComponents } from "./default-adapter.js";
+import { DesignSystemErrorBoundary } from "./error-boundary.js";
+import type {
+  ActionButtonProps,
+  AvatarProps,
+  CheckboxProps,
+  DesignSystemComponentName,
+  DesignSystemComponents,
+  DesignSystemKey,
+  DialogProps,
+  IconButtonProps,
+  MenuProps,
+  PickerProps,
+  PopoverProps,
+  SkeletonProps,
+  SpinnerProps,
+  StatusProps,
+  SurfaceProps,
+  SwitchProps,
+  TabsProps,
+  TextAreaProps,
+  TextFieldProps,
+  TooltipProps,
+} from "./types.js";
+
+function createComponent<Props extends object>(
+  name: DesignSystemComponentName,
+  DefaultComponent: ComponentType<Props>,
+) {
+  function DesignSystemComponent(props: Props) {
+    const CustomComponent = useDesignSystemComponent(name) as
+      | ComponentType<Props>
+      | undefined;
+    const fallback = <DefaultComponent {...props} />;
+    if (
+      !CustomComponent ||
+      CustomComponent === DefaultComponent ||
+      CustomComponent === DesignSystemComponent
+    ) {
+      return fallback;
+    }
+    return (
+      <DesignSystemErrorBoundary component={name} fallback={fallback}>
+        <CustomComponent {...props} />
+      </DesignSystemErrorBoundary>
+    );
+  }
+  DesignSystemComponent.displayName = `DesignSystem.${name}`;
+  return DesignSystemComponent;
+}
+
+export const ActionButton = createComponent<ActionButtonProps>(
+  "ActionButton",
+  defaultDesignSystemComponents.ActionButton,
+);
+export const IconButton = createComponent<IconButtonProps>(
+  "IconButton",
+  defaultDesignSystemComponents.IconButton,
+);
+export const TextField = createComponent<TextFieldProps>(
+  "TextField",
+  defaultDesignSystemComponents.TextField,
+);
+export const TextArea = createComponent<TextAreaProps>(
+  "TextArea",
+  defaultDesignSystemComponents.TextArea,
+);
+export const Spinner = createComponent<SpinnerProps>(
+  "Spinner",
+  defaultDesignSystemComponents.Spinner,
+);
+export const Skeleton = createComponent<SkeletonProps>(
+  "Skeleton",
+  defaultDesignSystemComponents.Skeleton,
+);
+export const Status = createComponent<StatusProps>(
+  "Status",
+  defaultDesignSystemComponents.Status,
+);
+export const Surface = createComponent<SurfaceProps>(
+  "Surface",
+  defaultDesignSystemComponents.Surface,
+);
+export const Avatar = createComponent<AvatarProps>(
+  "Avatar",
+  defaultDesignSystemComponents.Avatar,
+);
+export const Tooltip = createComponent<TooltipProps>(
+  "Tooltip",
+  defaultDesignSystemComponents.Tooltip,
+);
+export const Menu = createComponent<MenuProps>(
+  "Menu",
+  defaultDesignSystemComponents.Menu,
+);
+export const Popover = createComponent<PopoverProps>(
+  "Popover",
+  defaultDesignSystemComponents.Popover,
+);
+export const Dialog = createComponent<DialogProps>(
+  "Dialog",
+  defaultDesignSystemComponents.Dialog,
+);
+export const Checkbox = createComponent<CheckboxProps>(
+  "Checkbox",
+  defaultDesignSystemComponents.Checkbox,
+);
+export const Switch = createComponent<SwitchProps>(
+  "Switch",
+  defaultDesignSystemComponents.Switch,
+);
+
+export function Picker<Value extends DesignSystemKey = string>(
+  props: PickerProps<Value>,
+) {
+  const CustomComponent = useDesignSystemComponent("Picker") as
+    | DesignSystemComponents["Picker"]
+    | undefined;
+  const DefaultComponent = defaultDesignSystemComponents.Picker;
+  const fallback = <DefaultComponent {...props} />;
+  if (!CustomComponent || CustomComponent === DefaultComponent) return fallback;
+  return (
+    <DesignSystemErrorBoundary component="Picker" fallback={fallback}>
+      <CustomComponent {...props} />
+    </DesignSystemErrorBoundary>
+  );
+}
+
+export function Tabs<Value extends DesignSystemKey = string>(
+  props: TabsProps<Value>,
+) {
+  const CustomComponent = useDesignSystemComponent("Tabs") as
+    | DesignSystemComponents["Tabs"]
+    | undefined;
+  const DefaultComponent = defaultDesignSystemComponents.Tabs;
+  const fallback = <DefaultComponent {...props} />;
+  if (!CustomComponent || CustomComponent === DefaultComponent) return fallback;
+  return (
+    <DesignSystemErrorBoundary component="Tabs" fallback={fallback}>
+      <CustomComponent {...props} />
+    </DesignSystemErrorBoundary>
+  );
+}

package/corpus/toolkit/src/design-system/context.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext } from "react";
+
+import type { DesignSystemDefinition } from "./definition.js";
+import type {
+  DesignSystemComponentName,
+  DesignSystemComponents,
+} from "./types.js";
+
+export interface DesignSystemContextValue {
+  definition?: DesignSystemDefinition;
+  legacyActionButton?: DesignSystemComponents["ActionButton"];
+}
+
+export const DesignSystemContext = createContext<DesignSystemContextValue>({});
+export const LegacyButtonRenderContext = createContext(false);
+
+export function useDesignSystem(): DesignSystemDefinition | undefined {
+  return useContext(DesignSystemContext).definition;
+}
+
+export function useDesignSystemComponent<
+  Name extends DesignSystemComponentName,
+>(name: Name): DesignSystemComponents[Name] | undefined {
+  const context = useContext(DesignSystemContext);
+  const component = context.definition?.components?.[name];
+  if (component) return component as DesignSystemComponents[Name];
+  if (name === "ActionButton" && context.legacyActionButton) {
+    return context.legacyActionButton as DesignSystemComponents[Name];
+  }
+  return undefined;
+}