@shopbb/helium 0.3.1 → 0.5.0

package/src/components/AddressBookProvider.tsx

@@ -0,0 +1,279 @@
+/**
+ * <AddressBookProvider> + useAddressBook()
+ *
+ * 接管买家地址簿全部能力。内部走 Customer Account GraphQL（不直接 fetch REST），
+ * 让商家代码不需要关心后端实现细节。
+ *
+ * 鉴权：内部通过 ShopProvider 拿 apiUrl，通过浏览器 localStorage 读 buyer token
+ * （key: 'shopbb:buyer_token'）。商家也可以传 `tokenProvider` 自定义 token 取法。
+ *
+ * 用法：
+ *   <ShopProvider {...}>
+ *     <AddressBookProvider>
+ *       <App />
+ *     </AddressBookProvider>
+ *   </ShopProvider>
+ *
+ *   const { addresses, defaultAddress, createAddress, ... } = useAddressBook();
+ */
+
+import * as React from 'react';
+import { useShop } from './ShopProvider';
+
+export interface Address {
+  id: string;
+  firstName?: string | null;
+  lastName?: string | null;
+  company?: string | null;
+  address1?: string | null;
+  address2?: string | null;
+  city?: string | null;
+  district?: string | null;
+  province?: string | null;
+  provinceCode?: string | null;
+  country?: string | null;
+  countryCode?: string | null;
+  zip?: string | null;
+  phone?: string | null;
+  latitude?: number | null;
+  longitude?: number | null;
+  isDefault: boolean;
+}
+
+export interface AddressInput {
+  firstName?: string;
+  lastName?: string;
+  company?: string;
+  address1?: string;
+  address2?: string;
+  city?: string;
+  district?: string;
+  province?: string;
+  provinceCode?: string;
+  country?: string;
+  countryCode?: string;
+  zip?: string;
+  phone?: string;
+}
+
+export type AddressBookStatus = 'unauthenticated' | 'loading' | 'idle' | 'updating' | 'error';
+
+export interface AddressBookUserError {
+  field?: string[];
+  code?: string;
+  message: string;
+}
+
+export interface AddressBookContextValue {
+  addresses: Address[];
+  defaultAddress: Address | null;
+  status: AddressBookStatus;
+  error: string | null;
+  createAddress: (input: AddressInput, asDefault?: boolean) => Promise<{ address?: Address; userErrors: AddressBookUserError[] }>;
+  updateAddress: (id: string, input: AddressInput, asDefault?: boolean) => Promise<{ address?: Address; userErrors: AddressBookUserError[] }>;
+  deleteAddress: (id: string) => Promise<{ userErrors: AddressBookUserError[] }>;
+  setDefault: (id: string) => Promise<{ userErrors: AddressBookUserError[] }>;
+  refetch: () => Promise<void>;
+}
+
+const Ctx = React.createContext<AddressBookContextValue | null>(null);
+
+const DEFAULT_TOKEN_KEY = 'shopbb:buyer_token';
+
+export interface AddressBookProviderProps {
+  children: React.ReactNode;
+  /** 自定义 token 取法。默认 localStorage[DEFAULT_TOKEN_KEY] */
+  tokenProvider?: () => string | null;
+  /** 自动 fetch；默认 true */
+  fetchOnMount?: boolean;
+  /** Customer Account GraphQL endpoint。默认 ${shop.apiUrl 替换为 /customer/api/2026-04/graphql} */
+  endpoint?: string;
+}
+
+export function AddressBookProvider(props: AddressBookProviderProps) {
+  const { children, tokenProvider, fetchOnMount = true, endpoint: endpointProp } = props;
+  const shop = useShop();
+
+  const [addresses, setAddresses] = React.useState<Address[]>([]);
+  const [defaultAddress, setDefaultAddressState] = React.useState<Address | null>(null);
+  const [status, setStatus] = React.useState<AddressBookStatus>('loading');
+  const [error, setError] = React.useState<string | null>(null);
+
+  const endpoint = React.useMemo(() => {
+    if (endpointProp) return endpointProp;
+    try {
+      const u = new URL(shop.apiUrl);
+      return `${u.origin}/customer/api/2026-04/graphql`;
+    } catch {
+      return shop.apiUrl;
+    }
+  }, [endpointProp, shop.apiUrl]);
+
+  const getToken = React.useCallback(() => {
+    if (tokenProvider) return tokenProvider();
+    if (typeof localStorage === 'undefined') return null;
+    return localStorage.getItem(DEFAULT_TOKEN_KEY) || localStorage.getItem('shopflare:buyer_token');
+  }, [tokenProvider]);
+
+  const gql = React.useCallback(
+    async <T = any>(query: string, variables?: any): Promise<{ data?: T; errors?: any[] }> => {
+      const token = getToken();
+      if (!token) throw new Error('未登录');
+      const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ query, variables }),
+      });
+      return res.json();
+    },
+    [endpoint, getToken],
+  );
+
+  const refetch = React.useCallback(async () => {
+    const token = getToken();
+    if (!token) {
+      setStatus('unauthenticated');
+      setAddresses([]);
+      setDefaultAddressState(null);
+      return;
+    }
+    setStatus('loading');
+    try {
+      const result = await gql<{ customer: { defaultAddress: Address | null; addresses: { nodes: Address[] } } | null }>(
+        `query { customer { defaultAddress { id firstName lastName phone city district province address1 address2 country zip isDefault } addresses(first: 50) { nodes { id firstName lastName company phone city district province provinceCode country countryCode address1 address2 zip latitude longitude isDefault } } } }`,
+      );
+      if (result.errors?.length) throw new Error(result.errors[0].message);
+      const c = result.data?.customer;
+      setAddresses(c?.addresses?.nodes ?? []);
+      setDefaultAddressState(c?.defaultAddress ?? null);
+      setStatus('idle');
+      setError(null);
+    } catch (e: any) {
+      setError(e?.message ?? String(e));
+      setStatus('error');
+    }
+  }, [gql, getToken]);
+
+  React.useEffect(() => {
+    if (fetchOnMount) void refetch();
+  }, [fetchOnMount, refetch]);
+
+  const createAddress = React.useCallback(
+    async (input: AddressInput, asDefault?: boolean) => {
+      setStatus('updating');
+      try {
+        const result = await gql<{ customerAddressCreate: { customerAddress: Address | null; userErrors: AddressBookUserError[] } }>(
+          `mutation Create($a: MailingAddressInput!, $d: Boolean) {
+             customerAddressCreate(address: $a, defaultAddress: $d) {
+               customerAddress { id firstName lastName phone city district province address1 address2 country zip isDefault }
+               userErrors { field code message }
+             }
+           }`,
+          { a: input, d: asDefault ?? false },
+        );
+        if (result.errors?.length) throw new Error(result.errors[0].message);
+        const payload = result.data!.customerAddressCreate;
+        await refetch();
+        return { address: payload.customerAddress ?? undefined, userErrors: payload.userErrors };
+      } catch (e: any) {
+        setStatus('error');
+        setError(e?.message);
+        return { userErrors: [{ code: 'NETWORK_ERROR', message: e?.message ?? String(e) }] };
+      }
+    },
+    [gql, refetch],
+  );
+
+  const updateAddress = React.useCallback(
+    async (id: string, input: AddressInput, asDefault?: boolean) => {
+      setStatus('updating');
+      try {
+        const result = await gql<{ customerAddressUpdate: { customerAddress: Address | null; userErrors: AddressBookUserError[] } }>(
+          `mutation Upd($id: ID!, $a: MailingAddressInput!, $d: Boolean) {
+             customerAddressUpdate(addressId: $id, address: $a, defaultAddress: $d) {
+               customerAddress { id firstName lastName phone city district province address1 address2 country zip isDefault }
+               userErrors { field code message }
+             }
+           }`,
+          { id, a: input, d: asDefault },
+        );
+        if (result.errors?.length) throw new Error(result.errors[0].message);
+        const payload = result.data!.customerAddressUpdate;
+        await refetch();
+        return { address: payload.customerAddress ?? undefined, userErrors: payload.userErrors };
+      } catch (e: any) {
+        setStatus('error');
+        setError(e?.message);
+        return { userErrors: [{ code: 'NETWORK_ERROR', message: e?.message ?? String(e) }] };
+      }
+    },
+    [gql, refetch],
+  );
+
+  const deleteAddress = React.useCallback(
+    async (id: string) => {
+      setStatus('updating');
+      try {
+        const result = await gql<{ customerAddressDelete: { deletedAddressId: string | null; userErrors: AddressBookUserError[] } }>(
+          `mutation D($id: ID!) {
+             customerAddressDelete(addressId: $id) {
+               deletedAddressId
+               userErrors { field code message }
+             }
+           }`,
+          { id },
+        );
+        if (result.errors?.length) throw new Error(result.errors[0].message);
+        await refetch();
+        return { userErrors: result.data!.customerAddressDelete.userErrors };
+      } catch (e: any) {
+        setStatus('error');
+        setError(e?.message);
+        return { userErrors: [{ code: 'NETWORK_ERROR', message: e?.message ?? String(e) }] };
+      }
+    },
+    [gql, refetch],
+  );
+
+  const setDefault = React.useCallback(
+    async (id: string) => {
+      setStatus('updating');
+      try {
+        const result = await gql<{ customerDefaultAddressUpdate: { customer: any; userErrors: AddressBookUserError[] } }>(
+          `mutation SD($id: ID!) {
+             customerDefaultAddressUpdate(addressId: $id) {
+               customer { id }
+               userErrors { field code message }
+             }
+           }`,
+          { id },
+        );
+        if (result.errors?.length) throw new Error(result.errors[0].message);
+        await refetch();
+        return { userErrors: result.data!.customerDefaultAddressUpdate.userErrors };
+      } catch (e: any) {
+        setStatus('error');
+        setError(e?.message);
+        return { userErrors: [{ code: 'NETWORK_ERROR', message: e?.message ?? String(e) }] };
+      }
+    },
+    [gql, refetch],
+  );
+
+  const value: AddressBookContextValue = React.useMemo(
+    () => ({ addresses, defaultAddress, status, error, createAddress, updateAddress, deleteAddress, setDefault, refetch }),
+    [addresses, defaultAddress, status, error, createAddress, updateAddress, deleteAddress, setDefault, refetch],
+  );
+
+  return <Ctx.Provider value={value}>{children}</Ctx.Provider>;
+}
+
+export function useAddressBook(): AddressBookContextValue {
+  const v = React.useContext(Ctx);
+  if (!v) throw new Error('useAddressBook must be used inside <AddressBookProvider>');
+  return v;
+}
+
+export function useAddressBookOptional(): AddressBookContextValue | null {
+  return React.useContext(Ctx);
+}

package/src/components/AddressForm.tsx

@@ -0,0 +1,198 @@
+/**
+ * <AddressForm>
+ *
+ * 地址编辑 / 新增表单。**自带**：
+ *   - 表单 state（useState）
+ *   - 必填验证
+ *   - 调 useAddressBook().createAddress / updateAddress
+ *   - userErrors 显示
+ *   - loading 态
+ *
+ * 用法（新增）：
+ *   <AddressForm onSave={() => setCreating(false)} onCancel={...} />
+ *
+ * 用法（编辑）：
+ *   <AddressForm initial={editingAddress} onSave={...} onCancel={...} />
+ *
+ * 表单不带样式（用 data-* 钩子或商家自己 className 控制）。
+ */
+
+import * as React from 'react';
+import { useAddressBook, type Address, type AddressInput, type AddressBookUserError } from './AddressBookProvider';
+
+export interface AddressFormProps {
+  /** 传 = 编辑模式；不传 = 新增模式 */
+  initial?: Address;
+  /** 保存成功后触发 */
+  onSave?: (address?: Address) => void;
+  /** 取消按钮触发 */
+  onCancel?: () => void;
+  /** 自定义提交按钮文字 */
+  submitText?: string;
+  cancelText?: string;
+  /** 显示"设为默认"复选框，默认 true */
+  showDefaultCheckbox?: boolean;
+  /** 哪些字段必填，默认 ['firstName','phone','address1','city','province'] */
+  requiredFields?: Array<keyof AddressInput>;
+  className?: string;
+  /** i18n 文案覆盖 */
+  i18n?: Partial<AddressFormI18n>;
+}
+
+export interface AddressFormI18n {
+  firstName: string;
+  lastName: string;
+  company: string;
+  phone: string;
+  country: string;
+  province: string;
+  city: string;
+  district: string;
+  address1: string;
+  address2: string;
+  zip: string;
+  setDefault: string;
+  saving: string;
+}
+
+const DEFAULT_I18N: AddressFormI18n = {
+  firstName: '收货人',
+  lastName: '姓氏',
+  company: '公司',
+  phone: '手机号',
+  country: '国家',
+  province: '省',
+  city: '市',
+  district: '区',
+  address1: '详细地址',
+  address2: '地址补充',
+  zip: '邮编',
+  setDefault: '设为默认地址',
+  saving: '保存中…',
+};
+
+export function AddressForm(props: AddressFormProps) {
+  const {
+    initial, onSave, onCancel,
+    submitText = '保存',
+    cancelText = '取消',
+    showDefaultCheckbox = true,
+    requiredFields = ['firstName', 'phone', 'address1', 'city', 'province'],
+    className,
+    i18n: i18nOverride,
+  } = props;
+
+  const { createAddress, updateAddress } = useAddressBook();
+  const i18n = { ...DEFAULT_I18N, ...i18nOverride };
+
+  const [form, setForm] = React.useState<AddressInput>({
+    firstName: initial?.firstName ?? '',
+    lastName: initial?.lastName ?? '',
+    company: initial?.company ?? '',
+    phone: initial?.phone ?? '',
+    country: initial?.country ?? 'China',
+    countryCode: initial?.countryCode ?? 'CN',
+    province: initial?.province ?? '',
+    provinceCode: initial?.provinceCode ?? '',
+    city: initial?.city ?? '',
+    district: initial?.district ?? '',
+    address1: initial?.address1 ?? '',
+    address2: initial?.address2 ?? '',
+    zip: initial?.zip ?? '',
+  });
+  const [asDefault, setAsDefault] = React.useState(initial?.isDefault ?? false);
+  const [saving, setSaving] = React.useState(false);
+  const [errors, setErrors] = React.useState<AddressBookUserError[]>([]);
+
+  const update = (k: keyof AddressInput, v: string) => setForm((f) => ({ ...f, [k]: v }));
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    // 客户端必填校验
+    const missing = requiredFields.filter((k) => !(form[k] && String(form[k]).trim()));
+    if (missing.length > 0) {
+      setErrors([{ field: missing as string[], code: 'MISSING_FIELD', message: '请填写完整地址' }]);
+      return;
+    }
+    setSaving(true);
+    setErrors([]);
+    try {
+      const result = initial
+        ? await updateAddress(initial.id, form, asDefault)
+        : await createAddress(form, asDefault);
+      if (result.userErrors.length > 0) {
+        setErrors(result.userErrors);
+        return;
+      }
+      onSave?.(result.address);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  const isRequired = (k: keyof AddressInput) => requiredFields.includes(k);
+
+  return (
+    <form onSubmit={handleSubmit} data-address-form className={className}>
+      <div data-row>
+        <label>
+          <span>{i18n.firstName}{isRequired('firstName') && ' *'}</span>
+          <input value={form.firstName} onChange={(e) => update('firstName', e.target.value)} required={isRequired('firstName')} />
+        </label>
+        <label>
+          <span>{i18n.phone}{isRequired('phone') && ' *'}</span>
+          <input value={form.phone} onChange={(e) => update('phone', e.target.value)} required={isRequired('phone')} type="tel" />
+        </label>
+      </div>
+      <div data-row data-row-3>
+        <label>
+          <span>{i18n.province}{isRequired('province') && ' *'}</span>
+          <input value={form.province} onChange={(e) => update('province', e.target.value)} required={isRequired('province')} />
+        </label>
+        <label>
+          <span>{i18n.city}{isRequired('city') && ' *'}</span>
+          <input value={form.city} onChange={(e) => update('city', e.target.value)} required={isRequired('city')} />
+        </label>
+        <label>
+          <span>{i18n.district}</span>
+          <input value={form.district} onChange={(e) => update('district', e.target.value)} />
+        </label>
+      </div>
+      <label>
+        <span>{i18n.address1}{isRequired('address1') && ' *'}</span>
+        <input value={form.address1} onChange={(e) => update('address1', e.target.value)} required={isRequired('address1')} />
+      </label>
+      <label>
+        <span>{i18n.address2}</span>
+        <input value={form.address2} onChange={(e) => update('address2', e.target.value)} />
+      </label>
+      <div data-row>
+        <label>
+          <span>{i18n.zip}</span>
+          <input value={form.zip} onChange={(e) => update('zip', e.target.value)} />
+        </label>
+        {showDefaultCheckbox && (
+          <label data-checkbox>
+            <input type="checkbox" checked={asDefault} onChange={(e) => setAsDefault(e.target.checked)} />
+            <span>{i18n.setDefault}</span>
+          </label>
+        )}
+      </div>
+      {errors.length > 0 && (
+        <div data-form-errors>
+          {errors.map((er, i) => (
+            <div key={i} data-error>{er.message}</div>
+          ))}
+        </div>
+      )}
+      <div data-actions>
+        {onCancel && (
+          <button type="button" onClick={onCancel} disabled={saving} data-action="cancel">{cancelText}</button>
+        )}
+        <button type="submit" disabled={saving} data-action="submit">
+          {saving ? i18n.saving : submitText}
+        </button>
+      </div>
+    </form>
+  );
+}

package/src/components/AddressList.tsx

@@ -0,0 +1,110 @@
+/**
+ * <AddressList>
+ *
+ * 渲染当前买家的地址列表。
+ *
+ * 用法：
+ *   <AddressList
+ *     onEdit={(addr) => openEditModal(addr)}
+ *     onAdd={() => openCreateModal()}
+ *     emptyText="还没有保存的地址"
+ *   />
+ */
+
+import * as React from 'react';
+import { useAddressBook, type Address } from './AddressBookProvider';
+
+export interface AddressListProps {
+  /** 编辑按钮点击 */
+  onEdit?: (address: Address) => void;
+  /** "新增" 按钮点击。不传 = 不显示新增按钮（商家自己渲染外面） */
+  onAdd?: () => void;
+  /** 空状态文案 */
+  emptyText?: React.ReactNode;
+  /** 渲染单个地址卡片的覆盖（高级用法） */
+  renderItem?: (address: Address, actions: AddressListItemActions) => React.ReactNode;
+  /** 整体容器 className */
+  className?: string;
+  /** 加载中渲染 */
+  loadingFallback?: React.ReactNode;
+}
+
+export interface AddressListItemActions {
+  setDefault: () => Promise<void>;
+  remove: () => Promise<void>;
+  edit?: () => void;
+}
+
+export function AddressList(props: AddressListProps) {
+  const {
+    onEdit, onAdd, emptyText = '还没有保存的地址',
+    renderItem, className, loadingFallback = null,
+  } = props;
+  const { addresses, status, setDefault, deleteAddress } = useAddressBook();
+
+  if (status === 'loading' || status === 'unauthenticated') {
+    return <>{loadingFallback}</>;
+  }
+
+  if (addresses.length === 0) {
+    return (
+      <div data-empty className={className}>
+        <p>{emptyText}</p>
+        {onAdd && (
+          <button type="button" onClick={onAdd} data-add-address>
+            + 新增地址
+          </button>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div data-address-list className={className}>
+      {onAdd && (
+        <div data-list-toolbar>
+          <span data-muted>{addresses.length} 个地址</span>
+          <button type="button" onClick={onAdd} data-add-address>+ 新增地址</button>
+        </div>
+      )}
+      <div data-items>
+        {addresses.map((a) => {
+          const actions: AddressListItemActions = {
+            setDefault: async () => { await setDefault(a.id); },
+            remove: async () => { await deleteAddress(a.id); },
+            edit: onEdit ? () => onEdit(a) : undefined,
+          };
+          if (renderItem) return <React.Fragment key={a.id}>{renderItem(a, actions)}</React.Fragment>;
+          return <DefaultAddressItem key={a.id} address={a} actions={actions} />;
+        })}
+      </div>
+    </div>
+  );
+}
+
+// 默认渲染
+function DefaultAddressItem({ address: a, actions }: { address: Address; actions: AddressListItemActions }) {
+  return (
+    <div data-address-item data-default={a.isDefault ? '' : undefined}>
+      <div data-row>
+        <div data-name>
+          {a.firstName || ''}{a.lastName || ''}
+          {a.isDefault && <span data-default-tag>默认</span>}
+        </div>
+        <div data-actions>
+          {!a.isDefault && (
+            <button type="button" onClick={actions.setDefault} data-action="default">设为默认</button>
+          )}
+          {actions.edit && (
+            <button type="button" onClick={actions.edit} data-action="edit">编辑</button>
+          )}
+          <button type="button" onClick={actions.remove} data-action="remove" data-danger>删除</button>
+        </div>
+      </div>
+      <div data-line>{a.phone || ''}</div>
+      <div data-line>
+        {a.province || ''}{a.city || ''}{a.district || ''}{a.address1 || ''}{a.address2 ? ' ' + a.address2 : ''}
+      </div>
+    </div>
+  );
+}