@77-zhike/app-sdk 0.2.0-d7b1.6 → 0.2.0-d7b1.7

package/src/toolchain/source-discovery.js

@@ -8,8 +8,13 @@ import { ZhikeCliError } from "../errors.js";
 
 const KEY_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
 const RECORD_OBJECT_PATTERN = /^[a-z][a-z0-9_]{0,106}$/;
+const RECORD_EXTENSION_OBJECT_PATTERN = /^(?:accounts|contacts|opportunities|custom_[a-z0-9_]{1,100})$/;
 const RECORD_ACTION_LABEL_MAX_LENGTH = 80;
 const RECORD_ACTION_OBJECTS_MAX_LENGTH = 32;
+const RECORD_ACTION_TYPES = new Set(["record-action", "object-action", "bulk-record-action"]);
+const RECORD_COMPONENT_TYPES = new Set(["record-widget", "record-section", "record-tab"]);
+const PAGE_NAME_MAX_LENGTH = 80;
+const PAGE_VARIANTS = new Set(["full", "centered"]);
 const SDK_ICON_NAMES = new Set(sdkIconNames);
 const SERVER_MODULE_PATTERN = /^server\/functions\/[a-z0-9][a-z0-9/-]*$/;
 const LIFECYCLE_EVENTS = new Set([
@@ -86,6 +91,9 @@ export async function discoverAppSources(projectDirectory) {
     const extensionMatch = file.relativePath.match(
       /^app\/extensions\/([a-z][a-z0-9-]{0,63})\/extension\.tsx$/,
     );
+    const pageMatch = file.relativePath.match(
+      /^app\/pages\/([a-z][a-z0-9-]{0,63})\/page\.tsx$/,
+    );
     const lifecycleMatch = file.relativePath.match(
       /^app\/events\/(app-installed|app-uninstalled|connection-added|connection-removed)\.event\.ts$/,
     );
@@ -103,6 +111,14 @@ export async function discoverAppSources(projectDirectory) {
       );
       registerUniqueKey(globalKeys, definition.key, file.relativePath);
       lifecycleEvents.push(definition);
+    } else if (pageMatch) {
+      const definition = parseWorkspacePage(
+        sourceFile,
+        file.relativePath,
+        pageMatch[1],
+      );
+      registerUniqueKey(globalKeys, definition.key, file.relativePath);
+      frontendExtensions.push(definition);
     } else if (extensionMatch) {
       const definition = parseFrontendExtension(
         sourceFile,
@@ -221,16 +237,21 @@ function parseFrontendExtension(sourceFile, relativePath, directoryKey) {
   const key = requireStringProperty(object, "key", relativePath);
   const type = requireStringProperty(object, "type", relativePath);
   const point = frontendPoint(type);
-  if (!point) throw toolchainError("zhike_frontend_extension_type_unsupported", `${relativePath}: 扩展类型尚未开放`);
-  const handlerName = point.kind === "view" ? "component" : (point.callbackName || "handler");
+  if (!point || type === "page") throw toolchainError("zhike_frontend_extension_type_unsupported", `${relativePath}: 扩展类型尚未开放`);
+  const handlerName = point.kind === "view" ? (point.componentName || "component") : (point.callbackName || "handler");
   const forbiddenNames = point.kind === "view"
-    ? ["handler", "onTrigger"]
-    : ["component", ...(handlerName === "handler" ? ["onTrigger"] : ["handler"])];
+    ? ["component", "Widget", "Section", "Tab", "Page", "handler", "onTrigger"].filter(name => name !== handlerName)
+    : ["component", "Widget", "Section", "Tab", "Page", ...(handlerName === "handler" ? ["onTrigger"] : ["handler"])];
   if (forbiddenNames.some(name => findProperty(object, name))) {
     throw toolchainError("zhike_frontend_definition_mixed", `${relativePath}: component 与 handler 不得混填`);
   }
   const property = findProperty(object, handlerName);
-  if (point.kind === "view" && property && ts.isPropertyAssignment(property) && ts.isIdentifier(property.initializer)) {
+  if (
+    point.kind === "view" &&
+    property &&
+    ((ts.isPropertyAssignment(property) && ts.isIdentifier(property.initializer)) ||
+      ts.isShorthandPropertyAssignment(property))
+  ) {
     // 引用的组件由 TypeScript 检查可调用性；控制面不执行组件。
   } else {
     requireFunctionProperty(object, handlerName, relativePath);
@@ -241,7 +262,7 @@ function parseFrontendExtension(sourceFile, relativePath, directoryKey) {
       `${relativePath}: key 必须与扩展目录一致`,
     );
   }
-  if (type === "record-action") {
+  if (RECORD_ACTION_TYPES.has(type)) {
     return Object.freeze({
       key,
       type,
@@ -250,9 +271,90 @@ function parseFrontendExtension(sourceFile, relativePath, directoryKey) {
       ...parseRecordActionMetadata(object, relativePath),
     });
   }
+  if (RECORD_COMPONENT_TYPES.has(type)) {
+    return Object.freeze({
+      key,
+      type,
+      entry: key,
+      relativePath,
+      ...parseRecordComponentMetadata(object, relativePath, handlerName),
+    });
+  }
   return Object.freeze({ key, type, entry: key, relativePath });
 }
 
+function parseWorkspacePage(sourceFile, relativePath, slug) {
+  requireSdkNamedImport(
+    sourceFile,
+    relativePath,
+    "@77-zhike/app-sdk/client",
+    "definePage",
+  );
+  const call = requireDefaultExportCall(sourceFile, relativePath, "definePage");
+  const object = requireObjectLiteral(call.arguments[0], relativePath);
+  assertOnlyProperties(
+    object,
+    ["name", "order", "variant", "Page", "showInNavigation"],
+    relativePath,
+    "zhike_page_definition_invalid",
+    "Page definition 包含不支持的字段",
+  );
+
+  const rawName = requireStringProperty(object, "name", relativePath);
+  const name = rawName.trim();
+  if (
+    [...name].length === 0 ||
+    [...name].length > PAGE_NAME_MAX_LENGTH ||
+    /\p{Cc}/u.test(name)
+  ) {
+    throw toolchainError(
+      "zhike_page_name_invalid",
+      `${relativePath}: name trim 后必须是 1～${PAGE_NAME_MAX_LENGTH} 个非控制字符`,
+    );
+  }
+  const variant = requireStringProperty(object, "variant", relativePath);
+  if (!PAGE_VARIANTS.has(variant)) {
+    throw toolchainError(
+      "zhike_page_variant_invalid",
+      `${relativePath}: variant 必须是 full 或 centered`,
+    );
+  }
+  const orderProperty = findProperty(object, "order");
+  const order = orderProperty === undefined
+    ? undefined
+    : requireSafeIntegerProperty(orderProperty, relativePath);
+  const visibilityProperty = findProperty(object, "showInNavigation");
+  let showInNavigation;
+  if (visibilityProperty !== undefined) {
+    if (!ts.isPropertyAssignment(visibilityProperty)
+      || ![ts.SyntaxKind.TrueKeyword, ts.SyntaxKind.FalseKeyword].includes(visibilityProperty.initializer.kind)) {
+      throw toolchainError("zhike_page_visibility_invalid", `${relativePath}: showInNavigation 必须是静态布尔值`);
+    }
+    showInNavigation = visibilityProperty.initializer.kind === ts.SyntaxKind.TrueKeyword;
+  }
+  const pageProperty = findProperty(object, "Page");
+  if (
+    !pageProperty ||
+    !ts.isPropertyAssignment(pageProperty) ||
+    !(ts.isIdentifier(pageProperty.initializer) || isFunctionLike(pageProperty.initializer))
+  ) {
+    throw toolchainError(
+      "zhike_page_component_invalid",
+      `${relativePath}: Page 必须是 React component 标识符或函数`,
+    );
+  }
+  return Object.freeze({
+    key: slug,
+    type: "page",
+    entry: slug,
+    relativePath,
+    name,
+    ...(order === undefined ? {} : { order }),
+    ...(showInNavigation === undefined ? {} : { showInNavigation }),
+    variant,
+  });
+}
+
 function parseRecordActionMetadata(object, relativePath) {
   assertOnlyProperties(object, ["key", "type", "label", "icon", "objects", "onTrigger"], relativePath);
   const label = requireStringProperty(object, "label", relativePath).trim();
@@ -283,9 +385,48 @@ function parseRecordActionMetadata(object, relativePath) {
   };
 }
 
-function requireRecordObjects(property, relativePath) {
+function parseRecordComponentMetadata(object, relativePath, componentName) {
+  assertOnlyProperties(
+    object,
+    ["key", "type", "label", "objects", componentName],
+    relativePath,
+    "zhike_record_component_definition_invalid",
+    "Record Page component definition 包含不支持的字段",
+  );
+  const label = requireStringProperty(object, "label", relativePath).trim();
+  if (
+    [...label].length === 0 ||
+    [...label].length > RECORD_ACTION_LABEL_MAX_LENGTH ||
+    /\p{Cc}/u.test(label)
+  ) {
+    throw toolchainError(
+      "zhike_record_component_label_invalid",
+      `${relativePath}: label 必须是 1～${RECORD_ACTION_LABEL_MAX_LENGTH} 个非控制字符`,
+    );
+  }
+  const objectsProperty = findProperty(object, "objects");
+  const objects = objectsProperty
+    ? requireRecordObjects(
+        objectsProperty,
+        relativePath,
+        "zhike_record_component_objects_invalid",
+        true,
+      )
+    : null;
+  return {
+    label,
+    ...(objects === null ? {} : { objects }),
+  };
+}
+
+function requireRecordObjects(
+  property,
+  relativePath,
+  errorCode = "zhike_record_action_objects_invalid",
+  rejectDuplicates = false,
+) {
   if (!ts.isPropertyAssignment(property)) {
-    throw toolchainError("zhike_record_action_objects_invalid", `${relativePath}: objects 必须是字符串字面量或字符串字面量数组`);
+    throw toolchainError(errorCode, `${relativePath}: objects 必须是字符串字面量或字符串字面量数组`);
   }
   const initializer = property.initializer;
   const values = ts.isStringLiteral(initializer)
@@ -293,7 +434,7 @@ function requireRecordObjects(property, relativePath) {
     : ts.isArrayLiteralExpression(initializer)
       ? initializer.elements.map(item => {
           if (!ts.isStringLiteral(item)) {
-            throw toolchainError("zhike_record_action_objects_invalid", `${relativePath}: objects 必须是字符串字面量数组`);
+            throw toolchainError(errorCode, `${relativePath}: objects 必须是字符串字面量数组`);
           }
           return item.text;
         })
@@ -302,17 +443,24 @@ function requireRecordObjects(property, relativePath) {
     values === null ||
     values.length === 0 ||
     values.length > RECORD_ACTION_OBJECTS_MAX_LENGTH ||
-    values.some(value => !RECORD_OBJECT_PATTERN.test(value))
+    (rejectDuplicates && new Set(values).size !== values.length) ||
+    values.some(value => !RECORD_OBJECT_PATTERN.test(value) || !RECORD_EXTENSION_OBJECT_PATTERN.test(value))
   ) {
     throw toolchainError(
-      "zhike_record_action_objects_invalid",
-      `${relativePath}: objects 必须包含 1～${RECORD_ACTION_OBJECTS_MAX_LENGTH} 个合法公开对象标识`,
+      errorCode,
+      `${relativePath}: objects 只支持 accounts、contacts、opportunities 或 custom_*，且必须包含 1～${RECORD_ACTION_OBJECTS_MAX_LENGTH} 个合法公开对象标识`,
     );
   }
-  return Object.freeze([...new Set(values)]);
+  return Object.freeze(rejectDuplicates ? values : [...new Set(values)]);
 }
 
-function assertOnlyProperties(object, allowed, relativePath) {
+function assertOnlyProperties(
+  object,
+  allowed,
+  relativePath,
+  code = "zhike_frontend_definition_unknown_property",
+  message = "Frontend Extension 包含不支持的字段",
+) {
   const allowedNames = new Set(allowed);
   for (const property of object.properties) {
     const name = property.name && (
@@ -320,8 +468,8 @@ function assertOnlyProperties(object, allowed, relativePath) {
     ) ? property.name.text : null;
     if (!name || !allowedNames.has(name)) {
       throw toolchainError(
-        "zhike_frontend_definition_unknown_property",
-        `${relativePath}: Frontend Extension 包含不支持的字段`,
+        code,
+        `${relativePath}: ${message}`,
       );
     }
   }
@@ -571,6 +719,20 @@ function rejectUnsupportedPaths(files) {
         `${path}: Frontend Extension 必须使用约定目录`,
       );
     }
+    if (/^app\/pages\/[^/]+\/page\.tsx$/.test(path)) {
+      const slug = path.split("/")[2];
+      if (!KEY_PATTERN.test(slug)) {
+        throw toolchainError(
+          "zhike_page_slug_invalid",
+          `${path}: Page slug 必须是最多 64 字符的 lowercase kebab-case`,
+        );
+      }
+    } else if (path.startsWith("app/pages/") && /\/page\.(?:ts|tsx)$/.test(path)) {
+      throw toolchainError(
+        "zhike_page_location_invalid",
+        `${path}: Page 必须位于 src/app/pages/<slug>/page.tsx 一级目录`,
+      );
+    }
     if (
       path.startsWith("app/webhooks/") &&
       path.endsWith(".ts") &&
@@ -624,6 +786,30 @@ function requireStringArrayProperty(object, name, relativePath) {
   });
 }
 
+function requireSafeIntegerProperty(property, relativePath) {
+  if (!ts.isPropertyAssignment(property)) {
+    throw toolchainError(
+      "zhike_page_order_invalid",
+      `${relativePath}: order 必须是安全整数字面量`,
+    );
+  }
+  const initializer = property.initializer;
+  const value = ts.isNumericLiteral(initializer)
+    ? Number(initializer.text)
+    : ts.isPrefixUnaryExpression(initializer) &&
+        initializer.operator === ts.SyntaxKind.MinusToken &&
+        ts.isNumericLiteral(initializer.operand)
+      ? -Number(initializer.operand.text)
+      : Number.NaN;
+  if (!Number.isSafeInteger(value)) {
+    throw toolchainError(
+      "zhike_page_order_invalid",
+      `${relativePath}: order 必须是安全整数字面量`,
+    );
+  }
+  return value;
+}
+
 function requireFunctionProperty(object, name, relativePath, { requireAsync = false } = {}) {
   const property = findProperty(object, name);
   const functionNode =

package/src/ui/components.generated.js

@@ -1,2 +1,4 @@
 // 此文件由 scripts/generate-components.mjs 生成，请修改产品能力声明。
-export const componentTypes = Object.freeze(["Text","Icon","Stack","Section","Banner","Badge","LoadingState","Button","LookupCell","Tabs","TabsList","TabsTrigger","TabsContent","Table","TableHeader","TableBody","TableRow","TableCell"]);
+export const componentTypes = Object.freeze(["Icon","Stack","SplitLayout","SplitLayoutMain","SplitLayoutAside","SplitLayoutActions","Section","Banner","Badge","LoadingState","Card","Grid","EmptyState","Link","Button","Switch","LookupCell","Tabs","TabsList","TabsTrigger","TabsContent","Table","TableHeader","TableBody","TableRow","TableCell","Avatar","DescriptionList","DescriptionListItem","DescriptionListMenu","DescriptionListMenuItem","Divider","Json","ExternalLink","StatusBadge","TextBlock","TypographyTitle","TypographyBody","TypographyCaption","TableHeaderCell","WidgetTextWidget","WidgetTitle","WidgetTextPrimary","WidgetTextSecondary","WidgetLoading","WidgetDecoration"]);
+export const legacyComponentTypes = Object.freeze(["Text","Icon","Stack","SplitLayout","SplitLayoutMain","SplitLayoutAside","SplitLayoutActions","Section","Banner","Badge","LoadingState","Card","Grid","EmptyState","Link","Button","Switch","LookupCell","Tabs","TabsList","TabsTrigger","TabsContent","Table","TableHeader","TableBody","TableRow","TableCell","Avatar","DescriptionList","DescriptionListItem","DescriptionListMenu","DescriptionListMenuItem","Divider","Json","ExternalLink","StatusBadge","TextBlock","TypographyTitle","TypographyBody","TypographyCaption","TableHeaderCell","WidgetTextWidget","WidgetTitle","WidgetTextPrimary","WidgetTextSecondary","WidgetLoading","WidgetDecoration"]);
+export const badgeColors = Object.freeze(["amber","blue","cyan","green","grey","lavender","lime","orange","pink","purple","red","yellow"]);

package/src/ui/factory.js

@@ -1,9 +1,42 @@
-import { componentTypes } from './components.generated.js';
+import { componentTypes, legacyComponentTypes } from './components.generated.js';
 import { useNormalizedOptions } from '../forms/normalize-options.js';
+import { assertExternalUrl } from '../client/external-url.js';
+import { assertBannerActions, assertJsonValue } from './validation.js';
 
-export function createUiComponents(React) {
+export function createUiComponents(React, { legacy = false, useOwner = () => null, openExternal = () => Promise.reject(new Error('runtime_host_interaction_unavailable')) } = {}) {
   const TabValue = React.createContext(null);
-  return Object.fromEntries(componentTypes.map(type => [type, function RemoteComponent(props) {
+  const components = Object.fromEntries((legacy ? legacyComponentTypes : componentTypes).map(type => [type, function RemoteComponent(props) {
+    if (!legacy && type === 'TextBlock') return React.createElement(type, { ...props, align: props.align ?? 'left' });
+    if (!legacy && type === 'Badge' && props.tone !== undefined) throw new Error('Badge.tone 已移除，请使用 StatusBadge');
+    if (type === 'Avatar') {
+      const { src, ...rest } = props;
+      return React.createElement(type, { ...rest, ...(src == null ? {} : { src: assertExternalUrl(src) }) });
+    }
+    if (type === 'Json') {
+      assertJsonValue(props.data);
+      return React.createElement(type, props);
+    }
+    if (type === 'Banner') {
+      const { actions, onAction, ...rest } = props;
+      if (onAction !== undefined || (actions !== undefined && !Array.isArray(actions))) throw new Error('runtime_ui_contract_invalid');
+      if (!actions?.length) return React.createElement(type, rest);
+      // 显式复制 metadata 和 handler；调用期间 App 原地修改数组不能重定向旧动作。
+      const data = actions.map(action => ({ label: action.label, variant: action.variant }));
+      const handlers = actions.map(action => action.onTrigger);
+      assertBannerActions(data);
+      if (handlers.some(handler => typeof handler !== 'function')) throw new Error('runtime_ui_contract_invalid');
+      return React.createElement(type, { ...rest, actions: data, onAction(index) {
+        if (!Number.isSafeInteger(index) || index < 0 || index >= handlers.length) throw new Error('runtime_ui_contract_invalid');
+        return handlers[index]();
+      } });
+    }
+    if (type === 'ExternalLink') {
+      const owner = useOwner();
+      const { href: input, onOpen, ...rest } = props;
+      if (onOpen !== undefined) throw new Error('runtime_ui_contract_invalid');
+      const href = assertExternalUrl(input);
+      return React.createElement(type, { ...rest, href, onOpen: () => openExternal(owner, href) });
+    }
     if (type === 'Tabs') return React.createElement(TabValue.Provider, { value: props.value }, React.createElement(type, props));
     if (type === 'TabsContent') {
       const value = React.useContext(TabValue);
@@ -16,4 +49,18 @@ export function createUiComponents(React) {
     }
     return React.createElement(type, props);
   }]));
+  Object.assign(components.DescriptionList, { Item: components.DescriptionListItem, Menu: components.DescriptionListMenu });
+  components.DescriptionListMenu.Item = components.DescriptionListMenuItem;
+  Object.assign(components.Table, { Header: components.TableHeader, HeaderCell: components.TableHeaderCell, Body: components.TableBody, Row: components.TableRow, Cell: components.TableCell });
+  Object.assign(components.TableCell, { Avatar: components.Avatar, Badge: components.Badge });
+  Object.assign(components.SplitLayout, { Main: components.SplitLayoutMain, Aside: components.SplitLayoutAside, Actions: components.SplitLayoutActions });
+  components.Typography = Object.freeze({ Title: components.TypographyTitle, Body: components.TypographyBody, Caption: components.TypographyCaption });
+  components.Widget = Object.freeze({
+    TextWidget: components.WidgetTextWidget,
+    Title: components.WidgetTitle,
+    Text: Object.freeze({ Primary: components.WidgetTextPrimary, Secondary: components.WidgetTextSecondary }),
+    Loading: components.WidgetLoading,
+    Decoration: components.WidgetDecoration,
+  });
+  return components;
 }