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

package/src/forms/state.js

@@ -0,0 +1,92 @@
+import { assertJsonValue } from '../ui/validation.js';
+import { isDateTime, isPlainDate } from './values.js';
+import { assertRecordRef, recordObjectsForField } from './record-options.js';
+const fail = () => { throw new Error('runtime_form_state_invalid'); };
+const only = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+export function selectedNames(selection, fields) {
+  return selection === true ? Object.keys(fields) : Array.isArray(selection) ? selection : [];
+}
+export function assertFormStateSelection(selection, fields) {
+  only(selection, ['values', 'errors', 'submitting', 'validating', 'validatingFields', 'formError']);
+  for (const kind of ['values', 'errors', 'validatingFields']) {
+    const names = selection[kind];
+    if (names === undefined || names === true) continue;
+    if (!Array.isArray(names) || names.length > 30 || new Set(names).size !== names.length || names.some(name => typeof name !== 'string' || !Object.hasOwn(fields, name))) fail();
+  }
+  for (const key of ['submitting', 'validating', 'formError']) if (selection[key] !== undefined && typeof selection[key] !== 'boolean') fail();
+  return selection;
+}
+function assertValue(value, field) {
+  switch (field.type) {
+    case 'boolean': if (typeof value !== 'boolean') fail(); break;
+    case 'number': if (value !== null && (typeof value !== 'number' || !Number.isFinite(value))) fail(); break;
+    case 'plainDate': if (value !== null && !isPlainDate(value)) fail(); break;
+    case 'dateTime': if (value !== null && !isDateTime(value)) fail(); break;
+    case 'record': if (value !== null) assertRecordRef(value, recordObjectsForField(field)); break;
+    default: if (typeof value !== 'string' || value.length > 10000) fail();
+  }
+}
+export function assertFormStateSnapshot(snapshot, formId, fields, selection) {
+  assertJsonValue(snapshot);
+  assertFormStateSelection(selection, fields);
+  const keys = ['formId', 'revision', ...(selection.values !== undefined ? ['values'] : []), ...(selection.errors !== undefined ? ['errors'] : []), ...['submitting', 'validating', 'formError'].filter(key => selection[key]), ...(selection.validatingFields !== undefined ? ['validatingFields'] : [])];
+  only(snapshot, keys);
+  if (Object.keys(snapshot).length !== keys.length || snapshot.formId !== formId || !Number.isSafeInteger(snapshot.revision) || snapshot.revision < 1) fail();
+  if (selection.values !== undefined) {
+    const names = selectedNames(selection.values, fields);
+    only(snapshot.values, names);
+    if (Object.keys(snapshot.values).length !== names.length) fail();
+    for (const name of names) assertValue(snapshot.values[name], fields[name]);
+  }
+  if (selection.errors !== undefined) {
+    only(snapshot.errors, selectedNames(selection.errors, fields));
+    for (const value of Object.values(snapshot.errors)) if (typeof value !== 'string' || !value || value.length > 4096) fail();
+  }
+  for (const key of ['submitting', 'validating']) if (selection[key] && typeof snapshot[key] !== 'boolean') fail();
+  if (selection.formError && snapshot.formError !== null && (typeof snapshot.formError !== 'string' || !snapshot.formError || snapshot.formError.length > 4096)) fail();
+  if (selection.validatingFields !== undefined) {
+    only(snapshot.validatingFields, selectedNames(selection.validatingFields, fields));
+    if (Object.values(snapshot.validatingFields).some(value => typeof value !== 'boolean')) fail();
+  }
+  return snapshot;
+}
+export function freezeFormState(value) {
+  if (value && typeof value === 'object') { Object.values(value).forEach(freezeFormState); Object.freeze(value); }
+  return value;
+}
+export function initialFormState(formId, fields, initialValues, selection) {
+  const snapshot = { formId, revision: 1 };
+  if (selection.values !== undefined) snapshot.values = Object.fromEntries(selectedNames(selection.values, fields).map(name => {
+    const value = initialValues[name];
+    return [name, fields[name].type === 'dateTime' && value ? new Date(value).toISOString() : value && typeof value === 'object' ? { ...value } : value];
+  }));
+  if (selection.errors !== undefined) snapshot.errors = {};
+  for (const key of ['submitting', 'validating']) if (selection[key]) snapshot[key] = false;
+  if (selection.formError) snapshot.formError = null;
+  if (selection.validatingFields !== undefined) snapshot.validatingFields = {};
+  assertFormStateSnapshot(snapshot, formId, fields, selection);
+  return snapshot;
+}
+export function createWithState({ createElement, Fragment, useMemo, useState, useRef }, formId, schema, initialValues) {
+  function Observer({ selection, children }) {
+    const revision = useRef(0);
+    const [snapshot, setSnapshot] = useState(() => initialFormState(formId, schema.fields, initialValues, selection));
+    const onState = useMemo(() => next => {
+      assertFormStateSnapshot(next, formId, schema.fields, selection);
+      if (next.revision <= revision.current) return;
+      revision.current = next.revision;
+      setSnapshot(freezeFormState(next));
+    }, []);
+    const { formId: _, revision: _revision, ...state } = snapshot;
+    return createElement(Fragment, null,
+      createElement('FormStateObserver', { formId, selection, onState }),
+      children(freezeFormState(state)));
+  }
+  return function WithState({ selection, children }) {
+    assertFormStateSelection(selection, schema.fields);
+    if (typeof children !== 'function') fail();
+    return createElement(Observer, { key: JSON.stringify(selection), selection, children });
+  };
+}

package/src/forms/validation.d.ts

@@ -0,0 +1,9 @@
+export const VALIDATION_TIMEOUT_MS: 10000;
+export interface ValidationMetadata { fields: string[]; form: boolean; mode: 'onBlur' | 'onChange' | 'onSubmit'; }
+export interface ValidationRequest {
+  formId: string; runId: number; reason: 'blur' | 'change' | 'submit';
+  values: Record<string, string | boolean | number | import("./record-options.js").RecordRef | null>; fields: string[]; includeForm: boolean;
+}
+export interface ValidationResponse { formId: string; runId: number; fieldErrors: Record<string, string>; formError?: string; }
+export function assertValidationMetadata(value: unknown, fields: Record<string, unknown>): ValidationMetadata;
+export function assertValidationResponse(value: unknown, request: Pick<ValidationRequest, 'formId' | 'runId'>, fields: Record<string, unknown>): ValidationResponse;

package/src/forms/validation.js

@@ -0,0 +1,83 @@
+import { freezeFormState } from './state.js';
+import { isDateTime, isPlainDate } from './values.js';
+import { assertRecordRef, recordObjectsForField } from './record-options.js';
+
+export const VALIDATION_TIMEOUT_MS = 10000;
+const fail = () => { throw new Error('runtime_form_validation_invalid'); };
+const only = (value, keys) => {
+  if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !keys.includes(key))) fail();
+};
+const validMessage = value => typeof value === 'string' && value.trim() && value.length <= 300;
+export function assertValidationMetadata(value, fields) {
+  only(value, ['fields', 'form', 'mode']);
+  if (!Array.isArray(value.fields) || value.fields.length > 30 || new Set(value.fields).size !== value.fields.length
+    || value.fields.some(name => typeof name !== 'string' || !Object.hasOwn(fields, name))
+    || typeof value.form !== 'boolean' || !['onBlur', 'onChange', 'onSubmit'].includes(value.mode)) fail();
+  return value;
+}
+export function assertValidationResponse(value, request, fields) {
+  only(value, ['formId', 'runId', 'fieldErrors', 'formError']);
+  if (value.formId !== request.formId || value.runId !== request.runId) fail();
+  only(value.fieldErrors, Object.keys(fields));
+  if (Object.values(value.fieldErrors).some(error => !validMessage(error)) || value.formError !== undefined && !validMessage(value.formError)) fail();
+  return value;
+}
+function assertRequest(request, formId, fields, validators, validate) {
+  only(request, ['formId', 'runId', 'reason', 'values', 'fields', 'includeForm']);
+  if (request.formId !== formId || !Number.isSafeInteger(request.runId) || request.runId < 1
+    || !['blur', 'change', 'submit'].includes(request.reason) || typeof request.includeForm !== 'boolean'
+    || request.includeForm && !validate || !Array.isArray(request.fields) || new Set(request.fields).size !== request.fields.length
+    || request.fields.some(name => !Object.hasOwn(validators, name))) fail();
+  only(request.values, Object.keys(fields));
+  if (Object.keys(request.values).length !== Object.keys(fields).length) fail();
+  for (const [name, field] of Object.entries(fields)) {
+    const value = request.values[name];
+    if (field.type === 'boolean') { if (typeof value !== 'boolean') fail(); }
+    else if (field.type === 'record') { if (value !== null) assertRecordRef(value, recordObjectsForField(field)); }
+    else if (field.type === 'number') { if (value !== null && (typeof value !== 'number' || !Number.isFinite(value))) fail(); }
+    else if (['plainDate', 'dateTime'].includes(field.type)) { if (value !== null && !(field.type === 'plainDate' ? isPlainDate(value) : isDateTime(value))) fail(); }
+    else if (typeof value !== 'string' || value.length > 10000) fail();
+  }
+}
+export function createValidationCallback(formId, fields, validators, validate) {
+  let busy = false;
+  return async input => {
+    assertRequest(input, formId, fields, validators, validate);
+    if (busy) fail();
+    busy = true;
+    const request = freezeFormState(structuredClone(input));
+    let active = true, timer, position = 0;
+    const fieldErrors = {};
+    const runField = async () => {
+      while (active && position < request.fields.length) {
+        const name = request.fields[position++], value = request.values[name];
+        if (!fields[name].required && (value === '' || value === null)) continue;
+        for (const validator of validators[name]) {
+          if (!active) return;
+          const error = await validator(value);
+          if (!active) return;
+          if (error !== undefined) { if (!validMessage(error)) fail(); fieldErrors[name] = error; break; }
+        }
+      }
+    };
+    try {
+      return await Promise.race([
+        (async () => {
+          await Promise.all([runField(), runField()]);
+          if (!active) return;
+          const result = request.includeForm ? await validate(request.values) : undefined;
+          if (!active) return;
+          if (result !== undefined) { only(result, ['fieldErrors', 'formError']); }
+          // 字段 custom 错误优先于跨字段错误。
+          const response = { formId, runId: request.runId, fieldErrors: { ...result?.fieldErrors, ...fieldErrors }, ...(result?.formError === undefined ? {} : { formError: result.formError }) };
+          if (result?.fieldErrors !== undefined) {
+            only(result.fieldErrors, Object.keys(fields));
+            if (Object.values(result.fieldErrors).some(error => !validMessage(error))) fail();
+          }
+          return assertValidationResponse(response, request, fields);
+        })(),
+        new Promise((_, reject) => { timer = setTimeout(() => { active = false; reject(new Error('runtime_form_validation_timeout')); }, VALIDATION_TIMEOUT_MS); }),
+      ]);
+    } finally { active = false; busy = false; clearTimeout(timer); }
+  };
+}

package/src/forms/values.d.ts

@@ -0,0 +1,5 @@
+export function isPlainDate(value: unknown): value is string;
+export function isDateTime(value: unknown): value is string;
+export function parseNumberDraft(value: unknown): { value: number | null; error?: string };
+export function instantToLocal(value: string | null): string;
+export function localToInstant(value: string): { value: string | null; error?: string };

package/src/forms/values.js

@@ -0,0 +1,38 @@
+/** 平台值格式，不包含业务字段规则或缺省时区。 */
+export function isPlainDate(value) {
+  if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) return false;
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(0);
+  date.setUTCFullYear(year, month - 1, day);
+  return year > 0 && date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+export function isDateTime(value) {
+  if (typeof value !== 'string') return false;
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})$/.exec(value);
+  return Boolean(match && isPlainDate(match[1]) && +match[2] < 24 && +match[3] < 60 && +(match[4] ?? 0) < 60 && Number.isFinite(Date.parse(value)));
+}
+export function parseNumberDraft(value) {
+  if (value === null || value === '') return { value: null };
+  if (typeof value === 'number') return Number.isFinite(value) ? { value } : { value: null, error: '请输入有效数字' };
+  if (typeof value !== 'string' || value.length > 512 || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(value)) return { value: null, error: '请输入有效数字' };
+  const number = Number(value);
+  return Number.isFinite(number) ? { value: number } : { value: null, error: '请输入有效数字' };
+}
+const pad = value => String(value).padStart(2, '0');
+export function instantToLocal(value) {
+  if (!value) return '';
+  if (!isDateTime(value)) return value;
+  const date = new Date(value);
+  return `${String(date.getFullYear()).padStart(4, '0')}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+export function localToInstant(value) {
+  if (!value) return { value: null };
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})$/.exec(value);
+  if (!match || !isPlainDate(match[1]) || +match[2] > 23 || +match[3] > 59) return { value: null, error: '请输入有效日期时间' };
+  const wall = new Date(value);
+  const utc = new Date(value + ':00.000Z').getTime();
+  const offsets = new Set([-36, 0, 36].map(hours => new Date(wall.getTime() + hours * 3600000).getTimezoneOffset()));
+  const candidates = [...offsets].map(offset => new Date(utc + offset * 60000).toISOString()).filter(instant => instantToLocal(instant) === value);
+  if (candidates.length !== 1) return { value: null, error: '该本地时间不存在或有歧义，请选择其他时间' };
+  return { value: candidates[0] };
+}

package/src/server/index.d.ts

@@ -221,6 +221,21 @@ export interface WorkspaceConnection {
 /** 同步读取当前执行的连接快照；未连接或暂不可用时抛出安全错误，不在 getter 内刷新。 */
 export function getWorkspaceConnection(): Readonly<WorkspaceConnection>;
 
+/** 当前 Server Function 调用者在当前 Workspace 内的成员快照。 */
+export interface CurrentUser {
+  /** Workspace 成员 ID；不是平台全局 User ID。 */
+  workspaceMemberId: string;
+  /** 当前 Workspace 中的显示名称。 */
+  displayName: string;
+  /** 当前 Workspace 中的主邮箱。 */
+  primaryEmailAddress: string | null;
+  /** 当前平台用户头像；未绑定平台用户时为空。 */
+  avatarUrl: string | null;
+}
+
+/** 同步读取当前调用者；Lifecycle、Webhook 等无人触发入口会抛出 current_user_unavailable。 */
+export function getCurrentUser(): Readonly<CurrentUser>;
+
 /** Server Function 的一期函数合同。 */
 export type ServerFunction<TArgs extends JsonValue[] = JsonValue[], TResult extends JsonValue = JsonValue> =
   (...args: TArgs) => Promise<TResult>;

package/src/server/index.js

@@ -153,6 +153,26 @@ export function getWorkspaceConnection() {
   });
 }
 
+export function getCurrentUser() {
+  const current = globalThis.ZHIKE_CURRENT_USER;
+  if (
+    !current ||
+    typeof current !== "object" ||
+    typeof current.workspaceMemberId !== "string" ||
+    typeof current.displayName !== "string"
+  ) {
+    const error = new Error("current_user_unavailable");
+    error.code = "current_user_unavailable";
+    throw error;
+  }
+  return Object.freeze({
+    workspaceMemberId: current.workspaceMemberId,
+    displayName: current.displayName,
+    primaryEmailAddress: typeof current.primaryEmailAddress === "string" ? current.primaryEmailAddress : null,
+    avatarUrl: typeof current.avatarUrl === "string" ? current.avatarUrl : null,
+  });
+}
+
 // 仅兼容已构建的旧 Bundle；新源码入口由 .server.ts 的默认 async 函数确定。
 export function defineServerFunction(handler) {
   if (typeof handler !== "function") {

package/src/toolchain/real-build.js

@@ -1,3 +1,4 @@
+import { componentTypes } from '../ui/components.generated.js';
 import { createRequire } from "node:module";
 import { createHash } from "node:crypto";
 import { mkdir, rm, writeFile } from "node:fs/promises";
@@ -245,6 +246,24 @@ function createSdkBuildPlugin(projectDirectory, sources, target) {
   return {
     name: "zhike-app-sdk-runtime",
     setup(buildApi) {
+      if (target === "remote-client") {
+        // 新构建固化 authoring 默认值；Guest 仍为不可变旧 Bundle 提供兼容模块。
+        buildApi.onResolve({ filter: /^@77-zhike\/app-sdk\/ui$/ }, args => args.namespace === "zhike-ui-authoring"
+          ? { path: args.path, external: true }
+          : { path: args.path, namespace: "zhike-ui-authoring" });
+        buildApi.onLoad({ filter: /.*/, namespace: "zhike-ui-authoring" }, () => ({ loader: "js", contents: `
+          import * as ui from "@77-zhike/app-sdk/ui";
+          import { createElement } from "react";
+          export const TextBlock = props => createElement(ui.TextBlock, { ...props, align: props.align ?? "left" });
+          export const Badge = props => {
+            if (props.tone !== undefined) throw new Error("Badge.tone 已移除，请使用 StatusBadge");
+            return createElement(ui.Badge, props);
+          };
+          export const TableCell = Object.defineProperties(props => createElement(ui.TableCell, props), { Avatar: { get: () => ui.Avatar }, Badge: { value: Badge } });
+          export const Table = Object.defineProperties(props => createElement(ui.Table, props), { Header: { get: () => ui.Table.Header }, HeaderCell: { get: () => ui.Table.HeaderCell }, Body: { get: () => ui.Table.Body }, Row: { get: () => ui.Table.Row }, Cell: { value: TableCell } });
+          export const { ${[...componentTypes.filter(type => !["TextBlock", "Badge", "Table", "TableCell"].includes(type)), "Typography", "Widget"].join(", ")} } = ui;
+        ` }));
+      }
       if (target !== "remote-client") buildApi.onResolve({ filter: /^@77-zhike\/app-sdk\/(client|server)$/ }, (args) => ({
         external: target === "server" && args.path.endsWith("/server"),
         path: args.path,
@@ -254,7 +273,10 @@ function createSdkBuildPlugin(projectDirectory, sources, target) {
       }));
       buildApi.onLoad({ filter: /.*/, namespace: "zhike-sdk-runtime" }, (args) => {
         if (args.path.endsWith("/client")) {
-          return { contents: "export const defineFrontendExtension = (definition) => definition;", loader: "js" };
+          return {
+            contents: "export const defineFrontendExtension = (definition) => definition; export const definePage = (definition) => ({ ...definition, type: 'page' });",
+            loader: "js",
+          };
         }
         return { contents: "export const defineLifecycleEvent = (definition) => definition; export const defineServerFunction = (handler) => handler; export const defineWebhookHandler = (definition) => definition; export const createWebhookHandler = async () => { throw new Error('webhook_handler_runtime_unavailable'); }; export const listWebhookHandlers = async () => { throw new Error('webhook_handler_runtime_unavailable'); }; export const deleteWebhookHandler = async () => { throw new Error('webhook_handler_runtime_unavailable'); };", loader: "js" };
       });
@@ -293,7 +315,7 @@ function createManifest({ clientBytes, serverBytes, sources }) {
     sdkAbiVersion: "2",
     toolchainVersion: TOOLING_VERSION,
     ...(sources.frontendExtensions.length > 0
-      ? { clientRuntime: { runtimeVersion: "remote-react.v2" } } : {}),
+      ? { clientRuntime: { runtimeVersion: "remote-react.v3" } } : {}),
     artifacts: {
       ...(clientBytes
         ? {
@@ -316,7 +338,7 @@ function createManifest({ clientBytes, serverBytes, sources }) {
           }
         : {}),
     },
-    frontendExtensions: sources.frontendExtensions.map(({ key, type, entry, label, icon, objects }) => ({
+    frontendExtensions: sources.frontendExtensions.map(({ key, type, entry, label, icon, objects, name, order, variant, showInNavigation }) => ({
       artifact: "client",
       entry,
       key,
@@ -324,6 +346,10 @@ function createManifest({ clientBytes, serverBytes, sources }) {
       ...(label === undefined ? {} : { label }),
       ...(icon === undefined ? {} : { icon }),
       ...(objects === undefined ? {} : { objects }),
+      ...(name === undefined ? {} : { name }),
+      ...(order === undefined ? {} : { order }),
+      ...(variant === undefined ? {} : { variant }),
+      ...(showInNavigation === undefined ? {} : { showInNavigation }),
     })),
     lifecycleEvents: sources.lifecycleEvents.map(({ event, key }) => ({
       artifact: "server",