@shopbb/helium 0.3.1 → 0.4.0

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>
+  );
+}

package/src/components/AddressPicker.tsx

@@ -0,0 +1,152 @@
+/**
+ * <AddressPicker>
+ *
+ * Checkout 用的地址选择器。**自带**：
+ *   - 从 useAddressBook() 拿 list
+ *   - radio 渲染 + 默认选 defaultAddress
+ *   - 选 "新地址" 时展开新增表单
+ *
+ * 用法（受控）：
+ *   <AddressPicker
+ *     value={selectedAddressId}
+ *     onChange={(id, addr) => setSelectedAddressId(id)}
+ *     allowNewAddress
+ *     onUseNewAddress={(addr) => setInlineAddress(addr)}
+ *   />
+ *
+ * 用法（非受控）：
+ *   <AddressPicker onSelect={(addr) => ...} />
+ *   组件内部 state；选择后回调商家拿值。
+ */
+
+import * as React from 'react';
+import { useAddressBook, type Address } from './AddressBookProvider';
+import { AddressForm } from './AddressForm';
+
+export interface AddressPickerProps {
+  /** 受控：当前选中的 address ID */
+  value?: string | null;
+  /** 受控：选中变化（同时拿到 address 对象） */
+  onChange?: (addressId: string | null, address: Address | null) => void;
+  /** 非受控：选择时回调（不需要外面 state） */
+  onSelect?: (address: Address | null) => void;
+  /** 是否允许"使用新地址"选项 */
+  allowNewAddress?: boolean;
+  /** 选了"新地址"后填表保存的回调（拿到新建好的 Address） */
+  onUseNewAddress?: (address: Address) => void;
+  /** 空状态：没保存地址时显示什么。默认渲染内嵌 AddressForm */
+  emptyFallback?: React.ReactNode;
+  className?: string;
+}
+
+export function AddressPicker(props: AddressPickerProps) {
+  const {
+    value, onChange, onSelect,
+    allowNewAddress = true,
+    onUseNewAddress,
+    emptyFallback,
+    className,
+  } = props;
+  const { addresses, defaultAddress, status } = useAddressBook();
+
+  // 非受控 fallback
+  const [internalId, setInternalId] = React.useState<string | null>(null);
+  const selectedId = value !== undefined ? value : internalId;
+  const setSelectedId = React.useCallback((id: string | null, addr: Address | null) => {
+    if (value === undefined) setInternalId(id);
+    onChange?.(id, addr);
+    onSelect?.(addr);
+  }, [value, onChange, onSelect]);
+
+  const [showNewForm, setShowNewForm] = React.useState(false);
+
+  // 初次：自动选 default address
+  React.useEffect(() => {
+    if (selectedId == null && defaultAddress) {
+      setSelectedId(defaultAddress.id, defaultAddress);
+    } else if (selectedId == null && addresses.length > 0) {
+      setSelectedId(addresses[0].id, addresses[0]);
+    }
+  }, [defaultAddress, addresses, selectedId, setSelectedId]);
+
+  if (status === 'loading') {
+    return <div data-address-picker data-loading>加载地址中…</div>;
+  }
+
+  // 0 个地址：直接展示一个新增表单
+  if (addresses.length === 0) {
+    if (emptyFallback) return <>{emptyFallback}</>;
+    return (
+      <div data-address-picker data-empty className={className}>
+        <div data-picker-title>填写收货地址</div>
+        <AddressForm
+          onSave={(addr) => {
+            if (addr) {
+              setSelectedId(addr.id, addr);
+              onUseNewAddress?.(addr);
+            }
+          }}
+        />
+      </div>
+    );
+  }
+
+  return (
+    <div data-address-picker className={className}>
+      <div data-picker-title>选择收货地址</div>
+      <div data-picker-list>
+        {addresses.map((a) => (
+          <label key={a.id} data-picker-item data-active={selectedId === a.id ? '' : undefined}>
+            <input
+              type="radio"
+              name="address-picker"
+              checked={selectedId === a.id}
+              onChange={() => { setSelectedId(a.id, a); setShowNewForm(false); }}
+            />
+            <div>
+              <div data-name>
+                {a.firstName || ''}{a.lastName || ''}
+                {a.isDefault && <span data-default-tag>默认</span>}
+              </div>
+              <div data-line>
+                {a.phone} · {a.province}{a.city}{a.district || ''}{a.address1 || ''}
+              </div>
+            </div>
+          </label>
+        ))}
+        {allowNewAddress && (
+          <label data-picker-item data-active={showNewForm ? '' : undefined}>
+            <input
+              type="radio"
+              name="address-picker"
+              checked={showNewForm}
+              onChange={() => { setShowNewForm(true); setSelectedId(null, null); }}
+            />
+            <div>
+              <div data-name>+ 使用新地址</div>
+              <div data-line>填写一个新地址（默认保存到地址簿）</div>
+            </div>
+          </label>
+        )}
+      </div>
+      {showNewForm && allowNewAddress && (
+        <div data-new-address-form>
+          <AddressForm
+            onCancel={() => {
+              setShowNewForm(false);
+              const fallback = defaultAddress || addresses[0];
+              if (fallback) setSelectedId(fallback.id, fallback);
+            }}
+            onSave={(addr) => {
+              if (addr) {
+                setShowNewForm(false);
+                setSelectedId(addr.id, addr);
+                onUseNewAddress?.(addr);
+              }
+            }}
+          />
+        </div>
+      )}
+    </div>
+  );
+}