Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.
TypeScript ai-agentsbill-of-materialserpinventory-managementleanmanufacturingmanufacturing-execution-systemmcp-servermesmrpopen-source-erppostgresqlproduction-planningqmsquality-management-systemreact-routerself-hostedsupabasetraceabilitytypescript
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.
// `<StorageUnit>` — the storage-unit (bin) picker. One component, two modes:
// - with `name` -> form-bound (`@carbon/form` CreatableCombobox)
// - without `name` -> controlled (`value` + `onChange`) for table cells
//
// Options are the *leaf* storage units (the storable bins), each with a helper
// showing on-hand quantity (when `itemId` is given) or its hierarchy path.
// Built on the canonical `CreatableCombobox`, like every other entity picker.
//
// Choosing where a unit sits in the tree (a non-leaf target) is a different,
// single-purpose interaction handled by `StorageUnitParentSelect`, local to the
// Storage Unit form.
import type { TermId } from "@carbon/content/glossary";
import { CreatableCombobox } from "@carbon/form";
import { useLoaderQuery } from "@carbon/query";
import {
CreatableCombobox as CreatableComboboxBase,
useDisclosure
} from "@carbon/react";
import type { MouseEventHandler } from "react";
import { useMemo, useRef, useState } from "react";
import type { getStorageUnitsList } from "~/modules/inventory/inventory.service";
import StorageUnitForm from "~/modules/inventory/ui/StorageUnits/StorageUnitForm";
import type { ListItem } from "~/types";
import { path } from "~/utils/path";
import { useEmptyState } from "./emptyStates";
// ---------------------------------------------------------------------------
// Data hooks (shared)
// ---------------------------------------------------------------------------
export type StorageUnitTreeRow = {
id: string;
name: string;
parentId: string | null;
depth: number;
ancestorPath: string[];
};
/**
* Recursive storage-unit tree for a single location. One round-trip per
* locationId change; consumers cache by reference identity. Also used by the
* parent picker and storage-rule value inputs.
*/
export function useStorageUnitsTree(locationId?: string | null) {
const fetcher = useLoaderQuery<{
data: StorageUnitTreeRow[] | null;
error: unknown;
}>(locationId ? path.to.api.storageUnitsTree(locationId) : null);
return fetcher.data?.data ?? [];
}
/**
* Flat storage-unit list for a location, optionally with per-item quantity
* helpers. Kept for non-leaf-aware callsites that pull their own options.
*/
export function useStorageUnits(locationId?: string, itemId?: string) {
const storageUnitsFetcher = useLoaderQuery<
Awaited<ReturnType<typeof getStorageUnitsList>>
>(locationId ? path.to.api.storageUnits(locationId) : null);
const storageUnitsWithQuantitiesFetcher = useLoaderQuery<
Awaited<ReturnType<typeof getStorageUnitsList>>
>(
locationId && itemId
? path.to.api.storageUnitsWithQuantities(locationId, itemId)
: null,
{ staleTime: 0 }
);
const options = useMemo(() => {
if (itemId && storageUnitsWithQuantitiesFetcher.data?.data) {
const storageUnitsWithQuantities =
storageUnitsWithQuantitiesFetcher.data.data;
const allStorageUnits = storageUnitsFetcher.data?.data ?? [];
const storageUnitIdsWithQuantities = new Set(
storageUnitsWithQuantities.map((s: any) => s.id)
);
const storageUnitsWithoutQuantities = allStorageUnits.filter(
(storageUnit: any) => !storageUnitIdsWithQuantities.has(storageUnit.id)
);
return [
...storageUnitsWithQuantities.map((c: any) => ({
value: c.id,
label: c.name,
helper: `Qty: ${c.quantity}`
})),
...storageUnitsWithoutQuantities.map((c: any) => ({
value: c.id,
label: c.name
}))
];
}
return (
storageUnitsFetcher.data?.data?.map((c) => ({
value: c.id,
label: c.name,
// Add quantity as helper text if available
// @ts-expect-error
...(c.quantity !== undefined && { helper: `Qty: ${c.quantity}` })
})) ?? []
);
}, [
storageUnitsFetcher.data,
storageUnitsWithQuantitiesFetcher.data,
itemId
]);
return { options, data: storageUnitsFetcher.data };
}
type StorageUnitOption = { value: string; label: string; helper?: string };
/**
* Per-unit on-hand quantities for `itemId`, keyed by storage-unit id. Only
* fetches when both ids are present, so item-less pickers don't pay for it.
*/
function useStorageUnitQuantities(locationId?: string | null, itemId?: string) {
const fetcher = useLoaderQuery<{ data: { id: string; quantity: number }[] }>(
locationId && itemId
? path.to.api.storageUnitsWithQuantities(locationId, itemId)
: null,
{ staleTime: 0 }
);
return useMemo(() => {
const m = new Map<string, number>();
for (const s of fetcher.data?.data ?? []) m.set(s.id, s.quantity);
return m;
}, [fetcher.data]);
}
/**
* Options for the leaf bins in a location (nodes with no children — the
* storable locations). `helper` shows the on-hand quantity when `itemId` is
* given, otherwise the hierarchy path to disambiguate same-named bins.
*/
export function useStorageUnitLeafOptions(
locationId?: string | null,
itemId?: string
): StorageUnitOption[] {
const rows = useStorageUnitsTree(locationId);
const quantities = useStorageUnitQuantities(locationId, itemId);
return useMemo(() => {
const byId = new Map(rows.map((r) => [r.id, r]));
const parentIds = new Set(
rows.map((r) => r.parentId).filter((id): id is string => Boolean(id))
);
return rows
.filter((r) => !parentIds.has(r.id))
.map((r) => {
const ancestorPath = (r.ancestorPath ?? [])
.slice(0, -1)
.map((id) => byId.get(id)?.name)
.filter(Boolean)
.join(" / ");
return {
value: r.id,
label: r.name,
helper: itemId
? `Qty: ${quantities.get(r.id) ?? 0}`
: ancestorPath || undefined
};
})
.sort((a, b) => a.label.localeCompare(b.label));
}, [rows, quantities, itemId]);
}
// ---------------------------------------------------------------------------
// Create-new-unit flow
// ---------------------------------------------------------------------------
/**
* Shared "+ New storage unit" flow. `onCreateOption` seeds the form with the
* typed text; closing the modal re-clicks the trigger so the combobox reopens
* with the freshly created unit selectable.
*/
function useNewStorageUnitModal(locationId?: string | null) {
const modal = useDisclosure();
const [created, setCreated] = useState("");
const triggerRef = useRef<HTMLButtonElement>(null);
const node =
modal.isOpen && locationId ? (
<StorageUnitForm
type="modal"
locationId={locationId}
onClose={() => {
setCreated("");
modal.onClose();
triggerRef.current?.click();
}}
initialValues={{ name: created, locationId, storageTypeIds: [] }}
/>
) : null;
const onCreateOption = (value: string) => {
setCreated(value);
modal.onOpen();
};
return { triggerRef, onCreateOption, onOpen: modal.onOpen, node };
}
const storageUnitPreview = (
value: string,
options: { value: string; label: string | JSX.Element }[]
) => {
const match = options.find((o) => o.value === value);
return <span className="text-sm">{match?.label ?? ""}</span>;
};
const labelToString = (label: string | JSX.Element) =>
typeof label === "string" ? label : "";
// ---------------------------------------------------------------------------
// Component
// ---------------------------------------------------------------------------
type StorageUnitProps = {
/** Provide `name` for form-bound usage; omit it for controlled usage. */
name?: string;
/** Form-mode seed value, or the controlled value when `name` is absent. */
value?: string | null;
label?: string;
helperText?: string;
placeholder?: string;
isReadOnly?: boolean;
isOptional?: boolean;
disabled?: boolean;
className?: string;
onClick?: MouseEventHandler<HTMLButtonElement>;
locationId?: string | null;
itemId?: string;
/** Glossary term wired to a `<LabelWithHelp>` info icon next to the label. */
termId?: TermId;
/** Render a compact inline preview (table cells) once a value is set. */
inline?: boolean;
/** Show the "+ New storage unit" create option. Defaults to `true`. */
allowCreate?: boolean;
onChange?: (storageUnit: ListItem | null) => void;
};
const toListItem = (id: string, options: StorageUnitOption[]): ListItem => ({
id,
name: labelToString(options.find((o) => o.value === id)?.label ?? "")
});
function StorageUnit({
name,
value,
label,
helperText,
placeholder = "Select storage unit",
isReadOnly,
isOptional,
disabled,
className,
onClick,
locationId,
itemId,
termId,
inline,
allowCreate = true,
onChange
}: StorageUnitProps) {
const options = useStorageUnitLeafOptions(locationId, itemId);
const { triggerRef, onCreateOption, onOpen, node } =
useNewStorageUnitModal(locationId);
const readOnly = isReadOnly || disabled;
const emptyMessage = useEmptyState(
"storageUnit",
allowCreate && locationId ? { onCreate: onOpen } : undefined
);
if (name) {
return (
<>
<CreatableCombobox
ref={triggerRef}
name={name}
value={value ?? undefined}
options={options}
label={label ?? "Storage Unit"}
termId={termId}
helperText={helperText}
placeholder={placeholder}
isReadOnly={readOnly}
isOptional={isOptional}
className={className}
onClick={onClick}
inline={inline ? storageUnitPreview : undefined}
emptyMessage={emptyMessage}
onCreateOption={allowCreate ? onCreateOption : undefined}
onChange={(option) =>
onChange?.(
option
? { id: option.value, name: labelToString(option.label) }
: null
)
}
/>
{node}
</>
);
}
if (!locationId) return null;
return (
<>
<CreatableComboboxBase
ref={triggerRef}
options={options}
value={value ?? undefined}
isReadOnly={readOnly}
isClearable
placeholder={placeholder}
className={className}
onClick={onClick}
emptyMessage={emptyMessage}
onCreateOption={allowCreate ? onCreateOption : undefined}
onChange={(selected) =>
onChange?.(selected ? toListItem(selected, options) : null)
}
/>
{node}
</>
);
}
StorageUnit.displayName = "StorageUnit";
export default StorageUnit;