@ram_28/kf-ai-sdk 2.0.19 → 2.0.20-beta.1

package/docs/bdo/api_reference.md

@@ -1,281 +0,0 @@
-```typescript
-import { BaseBdo, StringField, NumberField, BooleanField, DateField, SelectField, ReferenceField } from "@ram_28/kf-ai-sdk/bdo";
-import type {
-  ItemType,
-  EditableFieldAccessorType,
-  ReadonlyFieldAccessorType,
-  ValidationResultType,
-  BdoMetaType,
-} from "@ram_28/kf-ai-sdk/bdo/types";
-import type {
-  ListOptionsType,
-  FilterType,
-  ConditionGroupType,
-  ConditionType,
-  SortType,
-  CreateUpdateResponseType,
-  DeleteResponseType,
-  MetricOptionsType,
-  MetricResponseType,
-  PivotOptionsType,
-  PivotResponseType,
-} from "@ram_28/kf-ai-sdk/api/types";
-import type {
-  StringFieldType,
-  NumberFieldType,
-  BooleanFieldType,
-  DateFieldType,
-  DateTimeFieldType,
-  TextFieldType,
-  SelectFieldType,
-  ReferenceFieldType,
-  UserFieldType,
-  FileFieldType,
-  ImageFieldType,
-  ArrayFieldType,
-  ObjectFieldType,
-  SystemFieldsType,
-} from "@ram_28/kf-ai-sdk/types";
-```
-
-## Methods
-
-All methods are `protected` on `BaseBdo`. Subclasses expose them as `public` per role.
-
-| Method | Params | Returns |
-|--------|--------|---------|
-| `get(id)` | `id: string` | `Promise<ItemType<TEditable, TReadonly>>` |
-| `list(options?)` | `options?: ListOptionsType` | `Promise<ItemType<TEditable, TReadonly>[]>` |
-| `count(options?)` | `options?: ListOptionsType` | `Promise<number>` |
-| `create(data)` | `data: Partial<TEditable>` | `Promise<ItemType<TEditable, TReadonly>>` |
-| `update(id, data)` | `id: string, data: Partial<TEditable>` | `Promise<CreateUpdateResponseType>` |
-| `delete(id)` | `id: string` | `Promise<DeleteResponseType>` |
-| `metric(options)` | `options: Omit<MetricOptionsType, "Type">` | `Promise<MetricResponseType>` |
-| `pivot(options)` | `options: Omit<PivotOptionsType, "Type">` | `Promise<PivotResponseType>` |
-
-## Types
-
-### ItemType\<TEditable, TReadonly\>
-
-Proxy-wrapped record returned by `get()`, `list()`, and `create()`. Provides typed field accessors for each field.
-
-```typescript
-type ItemType<TEditable, TReadonly> = {
-  readonly _id: string;               // direct string access
-
-  // Editable fields → EditableFieldAccessorType<T>
-  // Readonly fields → ReadonlyFieldAccessorType<T>
-
-  validate(): ValidationResultType;   // validates all fields
-  toJSON(): Partial<TEditable & TReadonly>;
-};
-```
-
-### EditableFieldAccessorType\<T\>
-
-Accessor for fields the current role can write.
-
-```typescript
-interface EditableFieldAccessorType<T> {
-  get(): T | undefined;
-  getOrDefault(fallback: T): T;
-  set(value: T): void;
-  validate(): ValidationResultType;
-  readonly label: string;
-  readonly required: boolean;
-  readonly readOnly: false;
-  readonly defaultValue: unknown;
-  readonly meta: BaseFieldMetaType;
-}
-```
-
-### ReadonlyFieldAccessorType\<T\>
-
-Accessor for fields the current role can only read. Same as editable but no `set()`.
-
-```typescript
-interface ReadonlyFieldAccessorType<T> {
-  get(): T | undefined;
-  getOrDefault(fallback: T): T;
-  validate(): ValidationResultType;
-  readonly label: string;
-  readonly required: boolean;
-  readonly readOnly: true;
-  readonly defaultValue: unknown;
-  readonly meta: BaseFieldMetaType;
-}
-```
-
-### ValidationResultType
-
-```typescript
-interface ValidationResultType {
-  valid: boolean;
-  errors: string[];
-}
-```
-
-### ListOptionsType
-
-```typescript
-interface ListOptionsType {
-  Filter?: FilterType;
-  Sort?: SortType;
-  Page?: number;       // 1-indexed
-  PageSize?: number;
-  Search?: string;
-  Field?: string[];    // specific fields to return
-}
-```
-
-### FilterType / ConditionGroupType / ConditionType
-
-```typescript
-// Root filter — alias for ConditionGroupType
-type FilterType = ConditionGroupType;
-
-interface ConditionGroupType {
-  Operator: "And" | "Or" | "Not";
-  Condition: Array<ConditionType | ConditionGroupType>;
-}
-
-interface ConditionType {
-  Operator: string;        // "eq", "neq", "gt", "gte", "lt", "lte", "contains", "startswith", etc.
-  LHSField: string;        // field name
-  RHSValue: any;            // comparison value
-  RHSType?: string;         // defaults to "Constant"
-}
-```
-
-### SortType
-
-```typescript
-type SortType = Record<string, "ASC" | "DESC">[];
-// Example: [{ "Price": "DESC" }, { "Title": "ASC" }]
-```
-
-### CreateUpdateResponseType
-
-```typescript
-interface CreateUpdateResponseType {
-  _id: string;
-}
-```
-
-### DeleteResponseType
-
-```typescript
-interface DeleteResponseType {
-  status: string;
-}
-```
-
-### MetricOptionsType
-
-Omit `Type` when calling `bdo.metric()` — it is added automatically.
-
-```typescript
-interface MetricOptionsType {
-  Type: "Metric";                  // omit when calling bdo.metric()
-  GroupBy: string[];
-  Metric: MetricFieldType[];
-  Filter?: FilterType;
-}
-
-interface MetricFieldType {
-  Field: string;
-  Type: string;   // "Count" | "Sum" | "Avg" | "Max" | "Min"
-}
-```
-
-### MetricResponseType
-
-```typescript
-interface MetricResponseType {
-  Data: Record<string, any>[];
-}
-```
-
-### PivotOptionsType
-
-Omit `Type` when calling `bdo.pivot()` — it is added automatically.
-
-```typescript
-interface PivotOptionsType {
-  Type: "Pivot";                   // omit when calling bdo.pivot()
-  Row: string[];
-  Column: string[];
-  Metric: MetricFieldType[];
-  Filter?: FilterType;
-}
-```
-
-### PivotResponseType
-
-```typescript
-interface PivotResponseType {
-  Data: {
-    RowHeader: PivotHeaderItemType[];
-    ColumnHeader: PivotHeaderItemType[];
-    Value: (number | string | null)[][];
-  };
-}
-
-interface PivotHeaderItemType {
-  Key: string;
-  Children?: PivotHeaderItemType[] | null;
-}
-```
-
-### SystemFieldsType
-
-Seven system-managed fields inherited from `BaseBdo`. Never redeclare in subclasses.
-
-```typescript
-type SystemFieldsType = {
-  _id: StringFieldType;
-  _created_at: DateTimeFieldType;
-  _modified_at: DateTimeFieldType;
-  _created_by: UserFieldType;
-  _modified_by: UserFieldType;
-  _version: StringFieldType;
-  _m_version: StringFieldType;
-};
-```
-
-### Field Value Types
-
-| Type | Resolves To |
-|------|-------------|
-| `StringFieldType` | `string` |
-| `TextFieldType` | `string` |
-| `NumberFieldType` | `number` |
-| `BooleanFieldType` | `boolean` |
-| `DateFieldType` | `"YYYY-MM-DD"` |
-| `DateTimeFieldType` | `"YYYY-MM-DDThh:mm:ssZ"` |
-| `SelectFieldType<T>` | `T` |
-| `ReferenceFieldType<T>` | `T` |
-| `UserFieldType` | `{ _id: string; _name: string }` |
-| `ImageFieldType` | `FileType \| null` |
-| `FileFieldType` | `FileType[]` |
-| `ArrayFieldType<T>` | `T[]` |
-| `ObjectFieldType<T>` | `T` |
-
-### Generated Type Patterns
-
-The js_sdk generator creates these types per entity:
-
-```typescript
-// entities/Product.ts
-export type ProductType = {
-  ProductId: StringFieldType;
-  Title: StringFieldType;
-  Price: NumberFieldType;
-  // ... business fields
-} & SystemFieldsType;
-
-// admin/Product.ts
-type AdminProductEditableFieldType = Omit<ProductType, keyof SystemFieldsType>;
-type AdminProductReadonlyFieldType = Record<string, never>;
-// or Pick<ProductType, "Field1" | "Field2"> for limited access
-```

package/docs/examples/bdo/create-product.md

@@ -1,69 +0,0 @@
-# Create Product
-
-> Create a new product using `useBDOForm` with validation, select fields, and submit handling.
-
-```tsx
-import { useMemo } from "react";
-import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
-import type { UseBDOFormReturnType } from "@ram_28/kf-ai-sdk/form/types";
-import { BuyerProduct } from "@/bdo/buyer/Product";
-import type { BuyerProductEntityType } from "@/bdo/buyer/Product";
-import type { FieldErrors } from "react-hook-form";
-
-export default function CreateProductForm() {
-  const product = useMemo(() => new BuyerProduct(), []);
-
-  const { register, handleSubmit, errors, isLoading, isSubmitting, watch, setValue }: UseBDOFormReturnType<BuyerProduct> =
-    useBDOForm({ bdo: product, defaultValues: { Title: "", Price: 0 } });
-
-  if (isLoading) return <p>Loading...</p>;
-
-  const onSuccess = (data: { _id: string }) => console.log("Created:", data._id);
-  const onError = (err: FieldErrors<BuyerProductEntityType> | Error) => {
-    if (err instanceof Error) console.error(err.message);
-  };
-
-  return (
-    <form onSubmit={handleSubmit(onSuccess, onError)}>
-      {/* Text input with register() */}
-      <label>{product.Title.label} {product.Title.required && <span>*</span>}</label>
-      <input {...register(product.Title.id)} />
-      {errors.Title && <p>{errors.Title.message}</p>}
-
-      <label>{product.Description.label}</label>
-      <textarea {...register(product.Description.id)} rows={3} />
-      {errors.Description && <p>{errors.Description.message}</p>}
-
-      {/* Number input with register() */}
-      <label>{product.Price.label} {product.Price.required && <span>*</span>}</label>
-      <input type="number" step="0.01" {...register(product.Price.id)} />
-      {errors.Price && <p>{errors.Price.message}</p>}
-
-      {/* Select field — watch/setValue, not register */}
-      <label>{product.Category.label} {product.Category.required && <span>*</span>}</label>
-      <select
-        value={watch(product.Category.id) ?? ""}
-        onChange={(e) => setValue(product.Category.id, e.target.value)}
-      >
-        <option value="">Select category</option>
-        {product.Category.options.map((opt) => (
-          <option key={opt.value} value={opt.value}>{opt.label}</option>
-        ))}
-      </select>
-      {errors.Category && <p>{errors.Category.message}</p>}
-
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? "Saving..." : "Add Product"}
-      </button>
-    </form>
-  );
-}
-```
-
-## Key Patterns
-
-- **Create mode** -- no `recordId` passed to `useBDOForm`; a draft is allocated on mount
-- **`register()`** -- for text and number inputs that fire native change events
-- **`watch()` + `setValue()`** -- for select fields and other custom components
-- **`handleSubmit(onSuccess, onError)`** -- validates, filters to editable fields, calls the API; never call `bdo.create()` manually
-- **Validation errors** -- `errors.FieldName.message` shows constraint violations automatically

package/docs/examples/bdo/edit-product-dialog.md

@@ -1,95 +0,0 @@
-# Edit Product Dialog
-
-> Click a table row to open an edit form in a dialog, save, and refetch the table.
-
-```tsx
-import { useState, useMemo } from "react";
-import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
-import type { UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
-import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
-import type { UseBDOFormReturnType } from "@ram_28/kf-ai-sdk/form/types";
-import { BuyerProduct } from "@/bdo/buyer/Product";
-import type { BuyerProductEntityType } from "@/bdo/buyer/Product";
-import type { FieldErrors } from "react-hook-form";
-
-export default function ProductPage() {
-  const [showForm, setShowForm] = useState(false);
-  const [selectedId, setSelectedId] = useState<string | null>(null);
-
-  const product = useMemo(() => new BuyerProduct(), []);
-
-  // ── Table ────────────────────────────────────────────────────
-  const table: UseBDOTableReturnType<BuyerProduct> = useBDOTable({
-    bdo: product,
-    initialState: { sort: [{ Title: "ASC" }], pagination: { pageNo: 1, pageSize: 10 } },
-  });
-
-  // ── Form (create when selectedId is null, edit when string) ──
-  const { register, handleSubmit, errors, isLoading: formLoading, isSubmitting, watch, setValue, isDirty }: UseBDOFormReturnType<BuyerProduct> =
-    useBDOForm({ bdo: product, recordId: selectedId ?? undefined });
-
-  const handleCreate = () => { setSelectedId(null); setShowForm(true); };
-  const handleEdit = (id: string) => { setSelectedId(id); setShowForm(true); };
-  const onSuccess = () => { setShowForm(false); setSelectedId(null); table.refetch(); };
-  const onError = (err: FieldErrors<BuyerProductEntityType> | Error) => {
-    if (err instanceof Error) console.error(err.message);
-  };
-
-  if (table.isLoading) return <p>Loading...</p>;
-
-  return (
-    <div>
-      <button onClick={handleCreate}>Add Product</button>
-
-      <table>
-        <thead>
-          <tr>
-            <th>{product.Title.label}</th>
-            <th>{product.Price.label}</th>
-          </tr>
-        </thead>
-        <tbody>
-          {table.rows.map((row) => (
-            <tr key={row._id} onClick={() => handleEdit(row._id)} style={{ cursor: "pointer" }}>
-              <td>{row.Title.get()}</td>
-              <td>${row.Price.get()?.toFixed(2)}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-
-      {/* Dialog form */}
-      {showForm && (
-        <dialog open>
-          <h2>{selectedId ? "Edit Product" : "Add Product"}</h2>
-          {formLoading ? (
-            <p>Loading form...</p>
-          ) : (
-            <form onSubmit={handleSubmit(onSuccess, onError)}>
-              <label>{product.Title.label}</label>
-              <input {...register(product.Title.id)} />
-              {errors.Title && <p>{errors.Title.message}</p>}
-
-              <label>{product.Price.label}</label>
-              <input type="number" step="0.01" {...register(product.Price.id)} />
-              {errors.Price && <p>{errors.Price.message}</p>}
-
-              <button type="button" onClick={() => setShowForm(false)}>Cancel</button>
-              <button type="submit" disabled={isSubmitting || (!!selectedId && !isDirty)}>
-                {isSubmitting ? "Saving..." : selectedId ? "Save Changes" : "Add Product"}
-              </button>
-            </form>
-          )}
-        </dialog>
-      )}
-    </div>
-  );
-}
-```
-
-## Key Patterns
-
-- **Shared BDO instance** -- `useMemo(() => new BuyerProduct(), [])` is passed to both `useBDOTable` and `useBDOForm`
-- **Create vs edit mode** -- `selectedId` is `null` for create (no `recordId`), or a string for edit
-- **`table.refetch()` after save** -- called in `onSuccess` to refresh the table data
-- **`isDirty` guard** -- disables the submit button in edit mode when no changes have been made

package/docs/examples/bdo/filtered-product-table.md

@@ -1,100 +0,0 @@
-# Filtered Product Table
-
-> Filter products by category and price range using the integrated `table.filter` API.
-
-```tsx
-import { useState, useMemo } from "react";
-import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
-import type { UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
-import { ConditionOperator, RHSType } from "@ram_28/kf-ai-sdk/filter";
-import { BuyerProduct } from "@/bdo/buyer/Product";
-
-export default function FilteredProductTable() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const table: UseBDOTableReturnType<BuyerProduct> = useBDOTable({ bdo: product });
-
-  // ── Category filter (single EQ condition) ─────────────────────
-  const [categoryFilter, setCategoryFilter] = useState("");
-  const [categoryConditionId, setCategoryConditionId] = useState<string | null>(null);
-
-  const handleCategoryFilter = (value: string) => {
-    if (categoryConditionId) {
-      table.filter.removeCondition(categoryConditionId);
-      setCategoryConditionId(null);
-    }
-    setCategoryFilter(value);
-    if (value && value !== "all") {
-      const id = table.filter.addCondition({
-        LHSField: "Category",
-        Operator: ConditionOperator.EQ,
-        RHSType: RHSType.Constant,
-        RHSValue: value,
-      });
-      setCategoryConditionId(id);
-    }
-  };
-
-  // ── Price range filter (GTE + LTE conditions) ─────────────────
-  const [minPrice, setMinPrice] = useState("");
-  const [maxPrice, setMaxPrice] = useState("");
-  const [minPriceConditionId, setMinPriceConditionId] = useState<string | null>(null);
-  const [maxPriceConditionId, setMaxPriceConditionId] = useState<string | null>(null);
-
-  const applyPriceFilter = () => {
-    if (minPriceConditionId) { table.filter.removeCondition(minPriceConditionId); setMinPriceConditionId(null); }
-    if (maxPriceConditionId) { table.filter.removeCondition(maxPriceConditionId); setMaxPriceConditionId(null); }
-
-    if (minPrice !== "") {
-      const id = table.filter.addCondition({
-        LHSField: "Price", Operator: ConditionOperator.GTE, RHSType: RHSType.Constant, RHSValue: Number(minPrice),
-      });
-      setMinPriceConditionId(id);
-    }
-    if (maxPrice !== "") {
-      const id = table.filter.addCondition({
-        LHSField: "Price", Operator: ConditionOperator.LTE, RHSType: RHSType.Constant, RHSValue: Number(maxPrice),
-      });
-      setMaxPriceConditionId(id);
-    }
-  };
-
-  if (table.isLoading) return <p>Loading...</p>;
-
-  return (
-    <div>
-      {/* Category dropdown */}
-      <select value={categoryFilter} onChange={(e) => handleCategoryFilter(e.target.value)}>
-        <option value="all">All categories</option>
-        {product.Category.options.map((opt) => (
-          <option key={opt.value} value={opt.value}>{opt.label}</option>
-        ))}
-      </select>
-
-      {/* Price range */}
-      <input type="number" placeholder="Min" value={minPrice} onChange={(e) => setMinPrice(e.target.value)} />
-      <input type="number" placeholder="Max" value={maxPrice} onChange={(e) => setMaxPrice(e.target.value)} />
-      <button onClick={applyPriceFilter}>Apply</button>
-
-      {/* Table */}
-      <table>
-        <tbody>
-          {table.rows.map((row) => (
-            <tr key={row._id}>
-              <td>{row.Title.get()}</td>
-              <td>${row.Price.get()?.toFixed(2)}</td>
-              <td>{row.Category.get()}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-    </div>
-  );
-}
-```
-
-## Key Patterns
-
-- **`addCondition()` returns an ID** -- store it in state to remove the condition later with `removeCondition(id)`
-- **Category filter** -- single `ConditionOperator.EQ` condition; remove-then-add on every change
-- **Price range** -- two separate conditions (`GTE` and `LTE`), each tracked by its own ID
-- **Filter changes auto-reset pagination** -- when conditions change, the table resets to page 1

package/docs/examples/bdo/product-listing.md

@@ -1,73 +0,0 @@
-# Product Listing
-
-> Browse products with search, sortable columns, and pagination using `useBDOTable`.
-
-```tsx
-import { useMemo } from "react";
-import { useBDOTable } from "@ram_28/kf-ai-sdk/table";
-import type { UseBDOTableReturnType } from "@ram_28/kf-ai-sdk/table/types";
-import { BuyerProduct } from "@/bdo/buyer/Product";
-
-export default function ProductListingPage() {
-  const product = useMemo(() => new BuyerProduct(), []);
-  const table: UseBDOTableReturnType<BuyerProduct> = useBDOTable({
-    bdo: product,
-    initialState: { sort: [{ _created_at: "DESC" }], pagination: { pageNo: 1, pageSize: 10 } },
-  });
-
-  if (table.isLoading) return <p>Loading...</p>;
-  if (table.error) return <p>Error: {table.error.message}</p>;
-
-  return (
-    <div>
-      {/* Search */}
-      <input
-        placeholder="Search by title..."
-        value={table.search.query}
-        onChange={(e) => table.search.set("Title", e.target.value)}
-      />
-      {table.search.query && <button onClick={table.search.clear}>Clear</button>}
-
-      {/* Table with sortable headers */}
-      <table>
-        <thead>
-          <tr>
-            <th onClick={() => table.sort.toggle("Title")} style={{ cursor: "pointer" }}>
-              {product.Title.label}
-              {table.sort.field === "Title" && (table.sort.direction === "ASC" ? " ↑" : " ↓")}
-            </th>
-            <th onClick={() => table.sort.toggle("Price")} style={{ cursor: "pointer" }}>
-              {product.Price.label}
-              {table.sort.field === "Price" && (table.sort.direction === "ASC" ? " ↑" : " ↓")}
-            </th>
-            <th>{product.Category.label}</th>
-          </tr>
-        </thead>
-        <tbody>
-          {table.rows.map((row) => (
-            <tr key={row._id}>
-              <td>{row.Title.get()}</td>
-              <td>${row.Price.get()?.toFixed(2)}</td>
-              <td>{row.Category.get()}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-
-      {/* Pagination */}
-      <div>
-        <button onClick={table.pagination.goToPrevious} disabled={!table.pagination.canGoPrevious}>Previous</button>
-        <span>Page {table.pagination.pageNo} of {table.pagination.totalPages}</span>
-        <button onClick={table.pagination.goToNext} disabled={!table.pagination.canGoNext}>Next</button>
-      </div>
-    </div>
-  );
-}
-```
-
-## Key Patterns
-
-- **`row.Field.get()`** -- rows are `ItemType` proxies; always use `.get()` to read values
-- **`search.set(field, query)`** -- updates the input instantly, debounces the API call (300ms)
-- **`sort.toggle(field)`** -- cycles ASC → DESC → cleared on each click
-- **Pagination** -- `canGoNext`/`canGoPrevious` disable buttons at boundaries; `pageNo`, `totalPages` for display

package/docs/examples/bdo/supplier-dropdown.md

@@ -1,60 +0,0 @@
-# Supplier Dropdown
-
-> Lazy-load ReferenceField options when the dropdown opens using `useQuery`.
-
-```tsx
-import { useState, useMemo } from "react";
-import { useQuery } from "@tanstack/react-query";
-import { useBDOForm } from "@ram_28/kf-ai-sdk/form";
-import type { UseBDOFormReturnType } from "@ram_28/kf-ai-sdk/form/types";
-import { BuyerProduct } from "@/bdo/buyer/Product";
-import type { ProductSupplierRefType } from "@/bdo/buyer/Product";
-
-export default function SupplierDropdown({ recordId }: { recordId?: string }) {
-  const [dropdownOpen, setDropdownOpen] = useState(false);
-  const product = useMemo(() => new BuyerProduct(), []);
-
-  const { watch, setValue, item }: UseBDOFormReturnType<BuyerProduct> = useBDOForm({ bdo: product, recordId });
-
-  // Lazy-load options only when dropdown opens and item has an _id
-  const { data: suppliers = [], isFetching } = useQuery<ProductSupplierRefType[]>({
-    queryKey: ["supplier-options", item._id],
-    queryFn: () => product.SupplierInfo.fetchOptions(item._id!),
-    enabled: dropdownOpen && !!item._id,
-    staleTime: Infinity,
-  });
-
-  const currentSupplier = watch(product.SupplierInfo.id);
-
-  return (
-    <div>
-      <label>{product.SupplierInfo.label}</label>
-      <select
-        value={currentSupplier?._id ?? ""}
-        onFocus={() => setDropdownOpen(true)}
-        onChange={(e) => {
-          const supplier = suppliers.find((s) => s._id === e.target.value);
-          if (supplier) setValue(product.SupplierInfo.id, supplier);
-        }}
-      >
-        <option value="">{currentSupplier?.SupplierName ?? "Select supplier"}</option>
-        {isFetching ? (
-          <option disabled>Loading...</option>
-        ) : (
-          suppliers.map((s) => (
-            <option key={s._id} value={s._id}>{s.SupplierName}</option>
-          ))
-        )}
-      </select>
-    </div>
-  );
-}
-```
-
-## Key Patterns
-
-- **`enabled: dropdownOpen && !!item._id`** -- options aren't fetched until the dropdown opens and the draft/record has an ID
-- **`fetchOptions(instanceId)`** -- loads reference options for the current record context
-- **`watch()` + `setValue()`** -- reads/writes the entire reference object (`{ _id, SupplierName }`)
-- **`referenceFields`** -- `product.SupplierInfo.referenceFields` lists the fields fetched from the referenced BDO
-- **`staleTime: Infinity`** -- options are cached and not refetched on re-focus