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

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

package/docs/examples/fields/complex-fields.md

@@ -1,248 +0,0 @@
-# Complex Fields
-
-> Complete form demonstrating selection, reference, and attachment fields with async options loading and pre-built UI components: Select, Reference, User, File, and Image.
-
-```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 type { UserFieldType } from "@ram_28/kf-ai-sdk/types";
-import { AdminFieldTest } from "@/bdo/admin/FieldTest";
-import type { FieldTestSupplierRefType } from "@/bdo/entities/field-test";
-import {
-  Field,
-  FieldContent,
-  FieldLabel,
-  FieldError,
-} from "@/components/ui/field";
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from "@/components/ui/select";
-import { ReferenceSelect } from "@/components/ui/reference-select";
-import { FileUpload } from "@/components/ui/file-upload";
-import { ImageUpload } from "@/components/ui/image-upload";
-import { FilePreview } from "@/components/ui/file-preview";
-import { ImageThumbnail } from "@/components/ui/image-thumbnail";
-
-export default function ComplexFieldsForm({ recordId }: { recordId?: string }) {
-  const fieldTest = useMemo(() => new AdminFieldTest(), []);
-
-  const {
-    watch,
-    setValue,
-    handleSubmit,
-    errors,
-    item,
-    isLoading,
-    isSubmitting,
-  }: UseBDOFormReturnType<AdminFieldTest> = useBDOForm({
-    bdo: fieldTest,
-    recordId,
-  });
-
-  // Dropdown open state for lazy-loading
-  const [userDropdownOpen, setUserDropdownOpen] = useState(false);
-
-  // ─── Async Options ─────────────────────────────────────────
-
-  // User field options — lazy-load when dropdown opens
-  const { data: users = [], isFetching: isUsersLoading } = useQuery<
-    UserFieldType[]
-  >({
-    queryKey: ["fieldtest-user-options", item._id],
-    queryFn: () => fieldTest.AssignedUser.fetchOptions(item._id!),
-    enabled: userDropdownOpen && !!item._id,
-    staleTime: Infinity,
-  });
-
-  if (isLoading) return <p>Loading...</p>;
-
-  return (
-    <form onSubmit={handleSubmit((data) => console.log("Saved", data._id))}>
-      {/* ───────────────────────────────────────────────── */}
-      {/* SelectField — static options from Constraint.Enum */}
-      {/* watch() + setValue(), NOT register()              */}
-      {/* ───────────────────────────────────────────────── */}
-      <Field>
-        <FieldLabel>
-          {fieldTest.Status.label} {fieldTest.Status.required && <span>*</span>}
-        </FieldLabel>
-        <FieldContent>
-          <Select
-            value={watch(fieldTest.Status.id) ?? ""}
-            onValueChange={(value) => setValue(fieldTest.Status.id, value)}
-          >
-            <SelectTrigger>
-              <SelectValue placeholder="Select status" />
-            </SelectTrigger>
-            <SelectContent>
-              {fieldTest.Status.options.map((opt) => (
-                <SelectItem key={opt.value} value={opt.value}>
-                  {opt.label}
-                </SelectItem>
-              ))}
-            </SelectContent>
-          </Select>
-        </FieldContent>
-        {errors.Status && <FieldError>{errors.Status.message}</FieldError>}
-      </Field>
-
-      {/* ───────────────────────────────────────────────── */}
-      {/* ReferenceField — pre-built <ReferenceSelect>     */}
-      {/* Abstracts fetchOptions + dropdown UI              */}
-      {/* ───────────────────────────────────────────────── */}
-      <Field>
-        <FieldLabel>{fieldTest.SupplierRef.label}</FieldLabel>
-        <FieldContent>
-          <ReferenceSelect
-            bdoField={fieldTest.SupplierRef}
-            instanceId={item._id}
-            value={watch(fieldTest.SupplierRef.id)}
-            onChange={(supplier) =>
-              setValue(
-                fieldTest.SupplierRef.id,
-                supplier as FieldTestSupplierRefType,
-              )
-            }
-          />
-        </FieldContent>
-        {errors.SupplierRef && <FieldError>{errors.SupplierRef.message}</FieldError>}
-      </Field>
-
-      {/* ───────────────────────────────────────────────── */}
-      {/* UserField — fetchOptions() + manual dropdown     */}
-      {/* Value shape: { _id: string; _name: string }      */}
-      {/* ───────────────────────────────────────────────── */}
-      <Field>
-        <FieldLabel>{fieldTest.AssignedUser.label}</FieldLabel>
-        <FieldContent>
-          <Select
-            value={watch(fieldTest.AssignedUser.id)?._id ?? ""}
-            onValueChange={(value) => {
-              const user = users.find((u) => u._id === value);
-              if (user) setValue(fieldTest.AssignedUser.id, user);
-            }}
-            open={userDropdownOpen}
-            onOpenChange={setUserDropdownOpen}
-          >
-            <SelectTrigger>
-              <SelectValue placeholder="Select user">
-                {watch(fieldTest.AssignedUser.id)?._name ?? "Select user"}
-              </SelectValue>
-            </SelectTrigger>
-            <SelectContent>
-              {isUsersLoading ? (
-                <div className="py-4 text-center text-sm text-gray-500">
-                  Loading...
-                </div>
-              ) : users.length > 0 ? (
-                users.map((user) => (
-                  <SelectItem key={user._id} value={user._id}>
-                    {user._name}
-                  </SelectItem>
-                ))
-              ) : (
-                <div className="py-4 text-center text-sm text-gray-500">
-                  No users available
-                </div>
-              )}
-            </SelectContent>
-          </Select>
-        </FieldContent>
-        {errors.AssignedUser && <FieldError>{errors.AssignedUser.message}</FieldError>}
-      </Field>
-
-      {/* ───────────────────────────────────────────────── */}
-      {/* FileField — <FileUpload> for edit mode           */}
-      {/* Runtime methods (upload, delete) on item accessor */}
-      {/* ───────────────────────────────────────────────── */}
-      <Field>
-        <FieldLabel>{fieldTest.Documents.label}</FieldLabel>
-        <FieldContent>
-          <FileUpload
-            field={fieldTest.Documents}
-            value={watch(fieldTest.Documents.id)}
-            boId={fieldTest.meta._id}
-            instanceId={item._id}
-            fieldId={fieldTest.Documents.id}
-          />
-        </FieldContent>
-      </Field>
-
-      {/* ───────────────────────────────────────────────── */}
-      {/* ImageField — <ImageUpload> for edit mode         */}
-      {/* Single image, nullable                           */}
-      {/* ───────────────────────────────────────────────── */}
-      <Field>
-        <FieldLabel>{fieldTest.Thumbnail.label}</FieldLabel>
-        <FieldContent>
-          <ImageUpload
-            field={fieldTest.Thumbnail}
-            value={watch(fieldTest.Thumbnail.id)}
-            boId={fieldTest.meta._id}
-            instanceId={item._id}
-            fieldId={fieldTest.Thumbnail.id}
-          />
-        </FieldContent>
-      </Field>
-
-      <button type="submit" disabled={isSubmitting}>
-        {isSubmitting ? "Saving..." : "Save"}
-      </button>
-    </form>
-  );
-}
-```
-
-## Read-Only Display
-
-For tables and detail pages, use `<FilePreview>` and `<ImageThumbnail>`:
-
-```tsx
-import { FilePreview } from "@/components/ui/file-preview";
-import { ImageThumbnail } from "@/components/ui/image-thumbnail";
-
-// In a table row or detail page
-function RecordRow({ record }: { record: ItemType<...> }) {
-  return (
-    <div>
-      {/* File preview — clickable thumbnails for images, file icons for others */}
-      <FilePreview
-        boId={fieldTest.meta._id}
-        instanceId={record._id}
-        fieldId="Documents"
-        value={record.Documents.get()}
-      />
-
-      {/* Image thumbnail — proxy URL with view_type=thumbnail */}
-      <ImageThumbnail
-        boId={fieldTest.meta._id}
-        instanceId={record._id}
-        fieldId="Thumbnail"
-        value={record.Thumbnail.get()}
-      />
-    </div>
-  );
-}
-```
-
-## Key Patterns
-
-- **All complex fields use `watch()` + `setValue()`** — never `register()`. Select, Reference, User, File, and Image fields use custom components that don't fire native change events.
-
-- **`fetchOptions()` lazy-loaded with `useQuery`** — Gate with `enabled: dropdownOpen && !!item._id` to avoid fetching until the dropdown opens. Use `staleTime: Infinity` to cache options.
-
-- **ReferenceField stores the full object** — Not just an ID. The value is `{ _id, SupplierName, Email, ... }`. The `setValue()` call must pass the complete object.
-
-- **File/Image runtime methods are on `item.Field`** — The `upload()`, `getDownloadUrl()`, `deleteAttachment()` methods live on the `item` accessor (created by the `Item` proxy), not on the BDO field class. The `<FileUpload>` and `<ImageUpload>` components handle this internally.
-
-- **`<ReferenceSelect>` abstracts the full pattern** — Handles `fetchOptions()`, dropdown UI, search, and option display. Pass `bdoField`, `instanceId`, `value`, and `onChange`.
-
-- **`<FileUpload>` / `<ImageUpload>` handle the upload lifecycle** — File selection, upload to storage, progress indication, preview, and delete. They need `boId`, `instanceId`, and `fieldId` for API calls.
-
-- **`<FilePreview>` / `<ImageThumbnail>` for read-only display** — Use in tables, detail pages, or any context where files should be viewable but not editable. They construct proxy URLs for same-origin access.