@isi-ui7/bos7-shared 0.2.3 → 0.2.6

package/src/form-value-schema.ts

@@ -0,0 +1,495 @@
+/**
+ * value_schema → bos7-shared form adapter (Wave C, core7-devroot#569).
+ *
+ * Turns a policy7 `parameter_categories.value_schema` (plain JSON Schema +
+ * the `x-ui` UI-hint extension + `x-rules` cross-field rules) into the
+ * `FormSection[]` + cross-field validator consumed by the EXISTING
+ * `CrudSchemaPage`. No new renderer.
+ *
+ * Pure: no fetch, no React. The category page fetches the schema (from #568),
+ * then composes `[scopeSection(t), ...buildValueSections(schema, t).sections]`
+ * and passes `validate` to the form.
+ *
+ * Spec: docs/plans/integration/PLAN-WC-XUI-CONVENTION.md
+ */
+import type { EditableColumnDef, EditableColumnType } from "@isi-ui7/editable-table";
+import { INDONESIA_CURRENCY_CONFIG } from "./form-numeric";
+import type {
+  DetailRowsConfig,
+  FormField,
+  FormFieldNumericConfig,
+  FormFieldOption,
+  FormFieldType,
+  FormMode,
+  FormSection,
+} from "./form-types";
+
+// ── i18n translate function ─────────────────────────────────────────────────
+export type T = (key: string, fallback?: string) => string;
+
+// ── JSON Schema + x-ui / x-rules shapes (the subset Wave C interprets) ───────
+
+export type XUiNumeric = {
+  kind: "currency" | "percent" | "integer" | "phone";
+  /** currency: name of the sibling field holding the currency code. */
+  currencyField?: string;
+  precisionByCurrency?: Record<string, number>;
+  defaultPrecision?: number;
+  /** percent. */
+  maxFractionDigits?: number;
+  /** phone. */
+  minDigits?: number;
+  maxDigits?: number;
+  allowedPrefixes?: string[];
+};
+
+export type XUiOption = { value: string; labelKey?: string; label?: string };
+
+export type XUiWidget =
+  | "text"
+  | "textarea"
+  | "number"
+  | "select"
+  | "date"
+  | "toggle"
+  | "lookup"
+  | "detail-rows";
+
+/** Per-property `x-ui` hint object (also array-level for `detail-rows`). */
+export type XUi = {
+  widget?: XUiWidget;
+  labelKey?: string;
+  label?: string;
+  helpKey?: string;
+  help?: string;
+  /** 1–12 grid width. Default 6. */
+  span?: number;
+  /** Sort order within an inferred section. */
+  order?: number;
+  /** Modes in which the field renders read-only, e.g. ["edit"]. */
+  readonlyOn?: FormMode[];
+  placeholder?: string;
+  numeric?: XUiNumeric;
+  /** `select` options (overrides enum labels). */
+  options?: XUiOption[];
+  /** Named dynamic-options source — deferred in Wave C (resolved by FE). */
+  optionsRef?: string;
+  lookup?: { api: string; valueField?: string; displayFields?: string[] };
+  toggle?: { valueOn?: unknown; valueOff?: unknown };
+  /** array `detail-rows`: max number of rows. */
+  maxRows?: number;
+};
+
+/** Root-level `x-ui` (layout grouping + density). */
+export type XUiRoot = XUi & {
+  layout?: {
+    sections?: Array<{ titleKey?: string; title?: string; fields: string[] }>;
+  };
+  density?: string;
+};
+
+export type JSONSchema = {
+  type?: string;
+  properties?: Record<string, JSONSchema>;
+  required?: string[];
+  enum?: unknown[];
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  default?: unknown;
+  items?: JSONSchema;
+  "x-ui"?: XUiRoot;
+  "x-rules"?: XRule[];
+};
+
+export type XRuleOp = "lte" | "gte" | "lt" | "gt" | "eq" | "required-if";
+
+export type XRule = {
+  op: XRuleOp;
+  left: string;
+  /** Other field to compare against (lte/gte/lt/gt/eq, or the condition field of required-if). */
+  right?: string;
+  /** Literal to compare against (eq) or the condition value (required-if). */
+  value?: unknown;
+  message?: string;
+  /** i18n key for the message (preferred over `message`). */
+  messageKey?: string;
+};
+
+type ValueData = Record<string, unknown>;
+export type ValueValidatorFn = (data: ValueData) => Partial<Record<string, string>>;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const DEFAULT_SPAN = 6;
+
+function resolveLabel(xui: XUi | undefined, fallback: string, t: T): string {
+  if (xui?.labelKey) return t(xui.labelKey, xui.label ?? fallback);
+  return xui?.label ?? fallback;
+}
+
+function resolveHelp(xui: XUi | undefined, t: T): string | undefined {
+  if (xui?.helpKey) return t(xui.helpKey, xui.help ?? "");
+  return xui?.help;
+}
+
+/** JSON Schema scalar type → bos7-shared field type, honoring `x-ui.widget`. */
+function inferFieldType(schema: JSONSchema, xui: XUi | undefined): FormFieldType {
+  if (xui?.widget) {
+    if (xui.widget === "lookup") return "lookup";
+    if (xui.widget === "detail-rows") return "detail-rows";
+    return xui.widget as FormFieldType;
+  }
+  switch (schema.type) {
+    case "boolean":
+      return "toggle";
+    case "integer":
+    case "number":
+      return "number";
+    case "array":
+      return "detail-rows";
+    case "string":
+    default:
+      if (Array.isArray(schema.enum)) return "select";
+      if (schema.format === "date" || schema.format === "date-time") return "date";
+      return "text";
+  }
+}
+
+function buildNumeric(
+  schema: JSONSchema,
+  xui: XUi | undefined,
+): FormFieldNumericConfig<ValueData> | undefined {
+  const n = xui?.numeric;
+  if (n) {
+    switch (n.kind) {
+      case "currency":
+        return {
+          kind: "currency",
+          currencyField: (n.currencyField ?? "currency") as keyof ValueData,
+          precisionByCurrency: n.precisionByCurrency ?? INDONESIA_CURRENCY_CONFIG.precisionByCurrency,
+          defaultPrecision: n.defaultPrecision ?? INDONESIA_CURRENCY_CONFIG.defaultPrecision,
+        };
+      case "percent":
+        return { kind: "percent", maxFractionDigits: n.maxFractionDigits ?? 2 };
+      case "integer":
+        return { kind: "integer" };
+      case "phone":
+        return {
+          kind: "phone",
+          minDigits: n.minDigits ?? 0,
+          maxDigits: n.maxDigits ?? 30,
+          allowedPrefixes: n.allowedPrefixes,
+        };
+    }
+  }
+  // No explicit numeric hint: integer JSON type still implies an integer field.
+  if (schema.type === "integer") return { kind: "integer" };
+  return undefined;
+}
+
+function buildOptions(schema: JSONSchema, xui: XUi | undefined, t: T): FormFieldOption[] | undefined {
+  if (xui?.options?.length) {
+    return xui.options.map((o) => ({
+      value: o.value,
+      label: o.labelKey ? t(o.labelKey, o.label ?? o.value) : (o.label ?? o.value),
+    }));
+  }
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.map((e) => ({ value: String(e), label: String(e) }));
+  }
+  return undefined;
+}
+
+/** plain JSON Schema constraints → FieldValidation (per-field). */
+function buildValidation(schema: JSONSchema, isRequired: boolean): FormField<ValueData>["validation"] {
+  const v: NonNullable<FormField<ValueData>["validation"]> = {};
+  if (isRequired) v.required = true;
+  if (typeof schema.minimum === "number") v.min = schema.minimum;
+  if (typeof schema.maximum === "number") v.max = schema.maximum;
+  if (typeof schema.minLength === "number") v.minLength = schema.minLength;
+  if (typeof schema.maxLength === "number") v.maxLength = schema.maxLength;
+  if (typeof schema.pattern === "string") v.pattern = new RegExp(schema.pattern);
+  return Object.keys(v).length ? v : undefined;
+}
+
+// ── detail-rows (array of object) ─────────────────────────────────────────────
+
+function defaultForColumn(schema: JSONSchema): unknown {
+  if (schema.default !== undefined) return schema.default;
+  switch (schema.type) {
+    case "integer":
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    default:
+      return "";
+  }
+}
+
+function buildColumnType(schema: JSONSchema, xui: XUi | undefined, t: T): EditableColumnType {
+  const type = inferFieldType(schema, xui);
+  const n = xui?.numeric;
+  if (n?.kind === "currency") {
+    return {
+      type: "currency",
+      precision: n.defaultPrecision ?? INDONESIA_CURRENCY_CONFIG.defaultPrecision,
+    };
+  }
+  if (n?.kind === "percent") {
+    return { type: "number", decimals: n.maxFractionDigits ?? 2, min: schema.minimum, max: schema.maximum };
+  }
+  if (n?.kind === "integer" || schema.type === "integer") {
+    return { type: "number", decimals: 0, min: schema.minimum, max: schema.maximum };
+  }
+  if (type === "number") {
+    return { type: "number", min: schema.minimum, max: schema.maximum };
+  }
+  if (type === "select") {
+    return { type: "select", options: buildOptions(schema, xui, t) ?? [] };
+  }
+  if (type === "date") return { type: "date" };
+  return { type: "text", maxLength: schema.maxLength, placeholder: xui?.placeholder };
+}
+
+function buildDetailRows(schema: JSONSchema, t: T): DetailRowsConfig | undefined {
+  const items = schema.items;
+  if (!items?.properties) return undefined;
+  const props = items.properties;
+  const required = new Set(items.required ?? []);
+  const entries = Object.entries(props);
+
+  const columns: EditableColumnDef[] = entries.map(([name, propSchema]) => {
+    const xui = propSchema["x-ui"];
+    return {
+      field: name,
+      header: resolveLabel(xui, name, t),
+      columnType: buildColumnType(propSchema, xui, t),
+      required: required.has(name),
+    };
+  });
+
+  const newRowFactory = (): Record<string, unknown> => {
+    const row: Record<string, unknown> = {};
+    for (const [name, propSchema] of entries) row[name] = defaultForColumn(propSchema);
+    return row;
+  };
+
+  const validateRow = (row: Record<string, unknown>): Record<string, string> => {
+    const errs: Record<string, string> = {};
+    for (const name of required) {
+      const val = row[name];
+      if (val === undefined || val === null || val === "") {
+        errs[name] = t("bos7.validRequired", "Wajib diisi");
+      }
+    }
+    return errs;
+  };
+
+  const xuiArr = schema["x-ui"];
+  return { columns, newRowFactory, validateRow, maxRows: xuiArr?.maxRows };
+}
+
+// ── Field builder ──────────────────────────────────────────────────────────────
+
+function buildField(name: string, schema: JSONSchema, isRequired: boolean, t: T): FormField<ValueData> {
+  const xui = schema["x-ui"];
+  const type = inferFieldType(schema, xui);
+  const field: FormField<ValueData> = {
+    key: name,
+    label: resolveLabel(xui, name, t),
+    type,
+    span: xui?.span ?? (type === "detail-rows" ? 12 : DEFAULT_SPAN),
+  };
+
+  const help = resolveHelp(xui, t);
+  if (help) field.helperText = help;
+  if (xui?.placeholder) field.placeholder = xui.placeholder;
+  if (typeof schema.maxLength === "number") field.maxLength = schema.maxLength;
+
+  if (xui?.readonlyOn?.length) {
+    const modes = xui.readonlyOn;
+    field.readonly = (mode) => modes.includes(mode);
+  }
+
+  if (type === "select") {
+    const options = buildOptions(schema, xui, t);
+    if (options) field.options = options;
+  }
+
+  if (type === "number") {
+    const numeric = buildNumeric(schema, xui);
+    if (numeric) field.numeric = numeric;
+    field.inputMode = numeric?.kind === "integer" ? "numeric" : "decimal";
+  }
+
+  if (type === "toggle" && xui?.toggle) {
+    field.toggle = { valueOn: xui.toggle.valueOn, valueOff: xui.toggle.valueOff };
+  }
+
+  if (type === "detail-rows") {
+    const detail = buildDetailRows(schema, t);
+    if (detail) field.detailRows = detail;
+  }
+
+  const validation = buildValidation(schema, isRequired);
+  if (validation) field.validation = validation;
+
+  return field;
+}
+
+// ── x-rules → cross-field validator ─────────────────────────────────────────────
+
+function toNumber(v: unknown): number | undefined {
+  if (v === null || v === undefined || v === "") return undefined;
+  const n = typeof v === "number" ? v : Number(v);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function isEmpty(v: unknown): boolean {
+  return v === null || v === undefined || v === "";
+}
+
+function ruleMessage(rule: XRule, t: T, fallback: string): string {
+  if (rule.messageKey) return t(rule.messageKey, rule.message ?? fallback);
+  return rule.message ?? fallback;
+}
+
+/**
+ * Build a form-level validator from `x-rules`. Comparison ops skip when either
+ * operand is empty/non-numeric (per-field `required` handles emptiness), so the
+ * cross-field check only fires on otherwise-complete input. Returns errors keyed
+ * by the offending field so the page blocks submit before `startWorkflow`.
+ */
+export function buildXRulesValidator(rules: XRule[] | undefined, t: T): ValueValidatorFn {
+  if (!rules?.length) return () => ({});
+  return (data) => {
+    const errors: Partial<Record<string, string>> = {};
+    for (const rule of rules) {
+      if (errors[rule.left]) continue; // first failing rule per field wins
+      switch (rule.op) {
+        case "lte":
+        case "gte":
+        case "lt":
+        case "gt": {
+          const left = toNumber(data[rule.left]);
+          const right = rule.right !== undefined ? toNumber(data[rule.right]) : toNumber(rule.value);
+          if (left === undefined || right === undefined) break;
+          const ok =
+            rule.op === "lte" ? left <= right :
+            rule.op === "gte" ? left >= right :
+            rule.op === "lt" ? left < right :
+            left > right;
+          if (!ok) errors[rule.left] = ruleMessage(rule, t, "Nilai tidak valid");
+          break;
+        }
+        case "eq": {
+          const expected = rule.right !== undefined ? data[rule.right] : rule.value;
+          if (isEmpty(data[rule.left])) break;
+          if (data[rule.left] !== expected) {
+            errors[rule.left] = ruleMessage(rule, t, "Nilai tidak sesuai");
+          }
+          break;
+        }
+        case "required-if": {
+          const condField = rule.right !== undefined ? data[rule.right] : undefined;
+          const conditionMet =
+            rule.value !== undefined ? condField === rule.value : !isEmpty(condField);
+          if (conditionMet && isEmpty(data[rule.left])) {
+            errors[rule.left] = ruleMessage(rule, t, "Wajib diisi");
+          }
+          break;
+        }
+      }
+    }
+    return errors;
+  };
+}
+
+// ── Section assembly ─────────────────────────────────────────────────────────
+
+function buildSections(
+  schema: JSONSchema,
+  fieldsByName: Map<string, FormField<ValueData>>,
+  orderByName: Map<string, number>,
+  t: T,
+): FormSection<ValueData>[] {
+  const layout = schema["x-ui"]?.layout;
+
+  if (layout?.sections?.length) {
+    const used = new Set<string>();
+    const sections: FormSection<ValueData>[] = layout.sections.map((sec) => {
+      const fields = sec.fields
+        .map((name) => {
+          used.add(name);
+          return fieldsByName.get(name);
+        })
+        .filter((f): f is FormField<ValueData> => Boolean(f));
+      const title = sec.titleKey ? t(sec.titleKey, sec.title ?? sec.titleKey) : sec.title;
+      return { title: title || undefined, fields };
+    });
+
+    // Any property not referenced by a layout section falls into a trailing group.
+    const leftover = [...fieldsByName.keys()].filter((name) => !used.has(name));
+    if (leftover.length) {
+      sections.push({
+        fields: leftover
+          .sort((a, b) => (orderByName.get(a) ?? 0) - (orderByName.get(b) ?? 0))
+          .map((name) => fieldsByName.get(name)!),
+      });
+    }
+    return sections;
+  }
+
+  // No layout hint → single "Value" section, fields sorted by x-ui.order.
+  const ordered = [...fieldsByName.keys()].sort(
+    (a, b) => (orderByName.get(a) ?? 0) - (orderByName.get(b) ?? 0),
+  );
+  return [
+    {
+      title: t("policy.section.value", "Value"),
+      fields: ordered.map((name) => fieldsByName.get(name)!),
+    },
+  ];
+}
+
+// ── Public adapter ──────────────────────────────────────────────────────────────
+
+/**
+ * Build the "value" form section(s) + a cross-field validator from a policy7
+ * `value_schema`. Pure; no fetch.
+ *
+ * @example
+ *   const { sections, validate } = buildValueSections(valueSchema, t);
+ *   const form: CrudForm<Data> = {
+ *     ...,
+ *     layout: { type: "single-page", sections: [scopeSection(t), ...sections] },
+ *     validate: (data) => ({ ...scopeValidate(data), ...validate(data) }),
+ *   };
+ */
+export function buildValueSections(
+  valueSchema: JSONSchema,
+  t: T,
+): { sections: FormSection<ValueData>[]; validate: ValueValidatorFn } {
+  const props = valueSchema.properties ?? {};
+  const required = new Set(valueSchema.required ?? []);
+
+  const fieldsByName = new Map<string, FormField<ValueData>>();
+  const orderByName = new Map<string, number>();
+
+  Object.entries(props).forEach(([name, propSchema], index) => {
+    fieldsByName.set(name, buildField(name, propSchema, required.has(name), t));
+    // Sort key: explicit x-ui.order, else original declaration order.
+    const order = propSchema["x-ui"]?.order;
+    orderByName.set(name, typeof order === "number" ? order : index);
+  });
+
+  const sections = buildSections(valueSchema, fieldsByName, orderByName, t);
+  const validate = buildXRulesValidator(valueSchema["x-rules"], t);
+
+  return { sections, validate };
+}

package/src/index.ts

@@ -17,4 +17,7 @@ export * from './notifications-bff';
 export * from './crud-types';
 export * from './crud-hooks';
 export * from './form-types';
+export * from './form-value-schema';
 export * from './i18n';
+export { proxyBackendPost, proxyQueryRoute } from './data-table/proxy';
+export type { ProxyBackendPostOptions, ProxyQueryRouteOptions } from './data-table/proxy';

package/src/shell/app-shell-layout.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import type { ReactNode } from "react";
+import type { ElementType, ReactNode } from "react";
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { useI18n, useUi7Labels, type Ui7Locale } from "@isi-ui7/i18n";
 import { useAuth as defaultUseAuth } from "../auth7";
@@ -20,7 +20,22 @@ export interface AppShellAuthState {
   logout: () => Promise<void> | void;
 }
 
-export type ShellNavItemLike = any;
+/**
+ * Structural shape of a side-nav item, mirroring ui-shell's `ShellNavItem`.
+ * `label`/`href` are required to stay mutually assignable with `ShellNavItem`:
+ * this type is used both covariantly (`navItems`) and contravariantly
+ * (`markActive`'s parameter), so consumers passing `ShellNavItem`-typed values
+ * would otherwise fail under `strict`. The index signature keeps it permissive
+ * for extra metadata (e.g. `requiredPermission`).
+ */
+export interface ShellNavItemLike {
+  label: string;
+  href: string;
+  isActive?: boolean;
+  icon?: string;
+  children?: ShellNavItemLike[];
+  [key: string]: unknown;
+}
 
 export interface ShellNotificationLike {
   id?: string;
@@ -57,39 +72,6 @@ interface NotificationBellOptionsLike {
   onNavigate?: (href: string) => void;
 }
 
-interface UiShellLikeProps {
-  productName: string;
-  headerPrefix: string;
-  headerThemeVariant: any;
-  navItems: any[];
-  sideNavItems: ShellNavItemLike[];
-  sideNavMode: string;
-  onSideNavSelect: (href: string) => void;
-  notifications: {
-    badgeCount: number;
-    /** Bumping this value forces ui-shell to re-fetch the panel list. */
-    fetchKey?: number;
-    onFetch: () => Promise<ShellNotificationLike[]>;
-    onMarkAllRead: () => void;
-    onItemClick: (n: ShellNotificationLike) => void;
-    viewAllHref: string;
-    viewAllTarget: string;
-  };
-  userProfile: {
-    name: string;
-    role?: string;
-    email: string;
-  };
-  profileActions: string[];
-  onProfileAction: (action: string) => void;
-  profileExtra?: ReactNode;
-  apps: {
-    onFetch: () => Promise<Array<{ href: string }>>;
-    onAppSelect: (app: { href: string }) => void;
-  };
-  children: ReactNode;
-}
-
 export type AppSwitchMode = "push" | "location";
 
 export interface AppShellLayoutDeps {
@@ -97,9 +79,9 @@ export interface AppShellLayoutDeps {
   useRouter: () => RouterLike;
   useTheme: () => { theme: ThemeLike };
   useNotificationBell: (opts: NotificationBellOptionsLike) => NotificationBellLike;
-  GlobalTheme: any;
-  ModalProvider: any;
-  UiShell: any;
+  GlobalTheme: ElementType;
+  ModalProvider: ElementType;
+  UiShell: ElementType;
   useAuth?: () => AppShellAuthState;
 }
 
@@ -139,7 +121,13 @@ function BranchDropdown({
       <button type="button" className="profile-branch-dropdown__trigger" onClick={() => setOpen((v) => !v)} aria-expanded={open}>
         <span className="profile-branch-dropdown__current">
           <span className="profile-branch-section__label" style={{ margin: 0 }}>{t("ui7.branchLabel", "Cabang")}</span>
-          <span className="profile-branch-item__code">{currentBranch?.code || currentBranch?.name || "—"}</span>
+          <span className="profile-branch-item__code">
+            {currentBranch
+              ? (currentBranch.code && currentBranch.name && currentBranch.code !== currentBranch.name
+                  ? `${currentBranch.code} — ${currentBranch.name}`
+                  : (currentBranch.code || currentBranch.name || "—"))
+              : "—"}
+          </span>
         </span>
         <span className="profile-branch-dropdown__chevron" aria-hidden="true">{open ? "▲" : "▼"}</span>
       </button>
@@ -297,7 +285,6 @@ export function AppShellLayout({
       corporateId={corporateId}
       appName={appName}
       auth7UiUrl={auth7UiUrl}
-      portalUrl={portalUrl}
       roleFallback={roleFallback}
       appSwitchMode={appSwitchMode}
       notificationsViewAllHref={notificationsViewAllHref ?? `${portalUrl}/notifications`}
@@ -306,7 +293,6 @@ export function AppShellLayout({
       disableAppsMenu={disableAppsMenu}
       sideNavMode={sideNavMode}
       sideNavItems={sideNavItems ?? resolvedSideNavItems}
-      resolvedSideNavItems={resolvedSideNavItems}
       notifBadgeCount={badgeCount}
       userName={user?.name}
       userEmail={user?.email}
@@ -350,7 +336,6 @@ function ShellInner({
   deps,
   appName,
   auth7UiUrl,
-  portalUrl,
   roleFallback,
   appSwitchMode,
   notificationsViewAllHref,
@@ -359,7 +344,6 @@ function ShellInner({
   disableAppsMenu,
   sideNavMode,
   sideNavItems,
-  resolvedSideNavItems,
   notifBadgeCount,
   userName,
   userEmail,
@@ -374,7 +358,6 @@ function ShellInner({
   deps: AppShellLayoutDeps;
   appName: string;
   auth7UiUrl: string;
-  portalUrl: string;
   roleFallback: string;
   appSwitchMode: AppSwitchMode;
   notificationsViewAllHref: string;
@@ -383,7 +366,6 @@ function ShellInner({
   disableAppsMenu: boolean;
   sideNavMode: "drilldown" | "overlay";
   sideNavItems: ShellNavItemLike[];
-  resolvedSideNavItems: ShellNavItemLike[];
   notifBadgeCount: number;
   userName?: string | null;
   userEmail?: string | null;
@@ -400,24 +382,49 @@ function ShellInner({
   const [currentBranch, setCurrentBranch] = useState<Branch | null>(null);
 
   useEffect(() => {
+    // API contract is snake_case (`branch_code`, `branch_name`); UI
+    // canonical fields are `code` and `name`. Map at the seam so downstream
+    // components stay clean. Empty branch_name falls back to branch_code as
+    // a visible label (rather than rendering an empty string).
+    type ApiBranch = {
+      id: string;
+      branch_code?: string;
+      branch_name?: string;
+      code?: string;
+      name?: string;
+      is_primary?: boolean;
+    };
+    const normalize = (b: ApiBranch): Branch => {
+      const code = b.branch_code ?? b.code ?? "";
+      const apiName = b.branch_name ?? b.name ?? "";
+      const name = apiName !== "" ? apiName : code;
+      return {
+        id: b.id,
+        name,
+        code,
+        is_primary: b.is_primary,
+        is_current: b.id === userBranchId,
+      };
+    };
+
     fetch("/api/auth/branches")
       .then((r) => (r.ok ? r.json() : null))
-      .then((d: { branches?: Branch[] } | null) => {
+      .then((d: { branches?: ApiBranch[] } | null) => {
         if (!d?.branches?.length) {
           if (userBranchId) {
-            const fallback = { id: userBranchId, name: userBranchId, code: userBranchId, is_current: true };
+            const fallback: Branch = { id: userBranchId, name: userBranchId, code: userBranchId, is_current: true };
             setBranches([fallback]);
             setCurrentBranch(fallback);
           }
           return;
         }
-        const normalized = d.branches.map((b: Branch) => ({ ...b, is_current: b.id === userBranchId }));
+        const normalized = d.branches.map(normalize);
         setBranches(normalized);
         setCurrentBranch(normalized.find((b) => b.is_current) ?? normalized[0]);
       })
       .catch(() => {
         if (userBranchId) {
-          const fallback = { id: userBranchId, name: userBranchId, code: userBranchId, is_current: true };
+          const fallback: Branch = { id: userBranchId, name: userBranchId, code: userBranchId, is_current: true };
           setBranches([fallback]);
           setCurrentBranch(fallback);
         }