docs(manufacturers): clarify PR 857 logo workflow comments

Author: akira69

client/src/components/otherModels.tsx

@@ -5,6 +5,7 @@ import { IFilament } from "../pages/filaments/model";
 import { IVendor } from "../pages/vendors/model";
 import { getAPIURL, getBasePath } from "../utils/url";
 
+// Build shared table-filter options here so spool/filament selectors reuse the same labels and tooltip metadata.
 export function useSpoolmanFilamentFilter(enabled: boolean = false) {
   return useQuery<IFilament[], unknown, ColumnFilterItem[]>({
     enabled: enabled,
@@ -17,13 +18,10 @@ export function useSpoolmanFilamentFilter(enabled: boolean = false) {
       return response.json();
     },
     select: (data) => {
-      // Concatenate vendor name and filament name
       const names = data
-        // Remove empty names
         .filter((filament) => {
           return filament.name !== null && filament.name !== undefined && filament.name !== "";
         })
-        // Transform to ColumnFilterItem
         .map((filament) => {
           let name = "";
           if (filament.vendor?.name) {
@@ -73,12 +71,11 @@ export function useSpoolmanFilamentFilter(enabled: boolean = false) {
               </Tooltip>
             ),
             value: filament.id,
+            // Preserve a plain string sort key so the dropdown stays alphabetized after wrapping with JSX.
             sortId: name,
           };
         })
-        // Remove duplicates
         .filter((item, index, self) => self.findIndex((t) => t.value === item.value) === index)
-        // Sort by name
         .sort((a, b) => a.sortId.localeCompare(b.sortId));
       return names;
     },
@@ -228,6 +225,7 @@ interface VendorLogoManifest {
   print_files?: string[];
 }
 
+// Missing bundled/runtime logo packs should degrade to empty suggestions instead of breaking vendor forms.
 export function useVendorLogoManifest(enabled: boolean = true) {
   return useQuery<VendorLogoManifest>({
     enabled,

client/src/components/vendorLogo.tsx

@@ -10,6 +10,7 @@ interface VendorLogoProps {
   fallbackStyle?: CSSProperties;
 }
 
+// Walk the vendor's candidate logo URLs in order, then optionally fall back to plain vendor text.
 export function VendorLogo({
   vendor,
   usePrintLogo = false,
@@ -20,6 +21,7 @@ export function VendorLogo({
   const candidates = useMemo(() => getVendorLogoCandidates(vendor, usePrintLogo), [vendor, usePrintLogo]);
   const [currentCandidateIndex, setCurrentCandidateIndex] = useState(0);
   useEffect(() => {
+    // Reset to the highest-priority candidate whenever the vendor or logo mode changes.
     setCurrentCandidateIndex(0);
   }, [vendor, usePrintLogo]);
 

client/src/pages/printing/exportDialog.tsx

@@ -20,6 +20,7 @@ interface ExportDialogProps {
   zipFileTypeName: string;
 }
 
+// Reuse the print-preview DOM for export so PNG and AML output always match the configured label layout.
 const ExportDialog = ({
   items,
   printSettings,
@@ -52,6 +53,7 @@ const ExportDialog = ({
   const itemHeight = Math.max(paperHeight - margin.top - margin.bottom, 0);
 
   const contentRef = useRef<HTMLDivElement>(null);
+  // AML consumers care about physical size, so exported PNGs need explicit pHYs DPI metadata.
   const pngSignature = new Uint8Array([137, 80, 78, 71, 13, 10, 26, 10]);
 
   const readUint32BE = (bytes: Uint8Array, offset: number) => {
@@ -204,6 +206,7 @@ const ExportDialog = ({
       .replace(/\.+$/g, "");
   };
 
+  // Export mode intentionally renders one label per preview page so filenames map 1:1 to saved files.
   const pageBlocks: ReactElement[][] = [];
   for (const item of items) {
     pageBlocks.push([item]);
@@ -406,6 +409,7 @@ const ExportDialog = ({
     };
   };
 
+  // Repeated copies share the same DOM shape, but export should still emit only one file per unique label design.
   const getUniqueExportItems = () => {
     const hasPrinted: Element[] = [];
     const itemsToPrint = getPrintItems();
@@ -414,7 +418,6 @@ const ExportDialog = ({
     let idx = 1;
 
     for (const item of itemsToPrint) {
-      // Prevent printing copies
       let isDuplicate = false;
       for (let i = 0; i < hasPrinted.length; i += 1) {
         if (item.isEqualNode(hasPrinted[i])) {

client/src/pages/printing/qrCodeExportDialog.tsx

@@ -57,6 +57,7 @@ interface QRCodeExportDialogProps {
   zipFileTypeName: string;
 }
 
+// Layer QR/logo/title export controls onto the shared export dialog used by spool and filament label flows.
 const QRCodeExportDialog = ({
   items,
   printSettings,
@@ -111,10 +112,12 @@ const QRCodeExportDialog = ({
   const bottomMargin = printSettings.printSettings?.margin?.bottom ?? 0;
   const containerPaddingMm = 1.2; // .print-qrcode-item vertical padding
   const minMainHeightMm = showQRCodeMode === "no" ? 0 : 8;
+  // Keep enough room for the QR/info area even when title and logo settings request a tall header.
   const availableContentHeightMm = Math.max(0, paperHeight - topMargin - bottomMargin - containerPaddingMm);
   const maxHeaderHeightMm = Math.max(0, availableContentHeightMm - minMainHeightMm);
   const preview =
     previewValues ?? ({ default: `WEB+SPOOLMAN:S-{id}`, url: `${baseUrlRoot}/spool/show/{id}` } as const);
+  // Show the actual fitted title size range from the preview, not just the configured maximum.
   const appliedTitleSizeDisplay = useMemo(() => {
     const values = Object.values(titleEffectiveTextSizesByItem).filter((value) => Number.isFinite(value));
     if (values.length === 0) {
@@ -128,6 +131,7 @@ const QRCodeExportDialog = ({
     return `${maxSize.toFixed(1)} mm`;
   }, [titleEffectiveTextSizesByItem, titleMaxTextSize]);
 
+  // Each label can shrink its title differently, so keep measurements per preview item for the settings summary.
   const elements = items.map((item, idx) => {
     const hasHeader = (showManufacturerLogo && !!item.vendor) || (showTitle && !!item.title);
     return (

client/src/pages/printing/qrCodePrintingDialog.tsx

@@ -55,6 +55,7 @@ interface QRCodePrintingDialogProps {
   previewValues?: { default: string; url: string };
 }
 
+// Layer QR/logo/title print controls onto the shared sheet-printing dialog used by spool and filament label flows.
 const QRCodePrintingDialog = ({
   items,
   printSettings,
@@ -107,10 +108,12 @@ const QRCodePrintingDialog = ({
   const bottomMargin = printSettings.printSettings?.margin?.bottom ?? 0;
   const containerPaddingMm = 1.2; // .print-qrcode-item vertical padding
   const minMainHeightMm = showQRCodeMode === "no" ? 0 : 8;
+  // Keep enough room for the QR/info area even when title and logo settings request a tall header.
   const availableContentHeightMm = Math.max(0, paperHeight - topMargin - bottomMargin - containerPaddingMm);
   const maxHeaderHeightMm = Math.max(0, availableContentHeightMm - minMainHeightMm);
   const preview =
     previewValues ?? ({ default: `WEB+SPOOLMAN:S-{id}`, url: `${baseUrlRoot}/spool/show/{id}` } as const);
+  // Show the actual fitted title size range from the preview, not just the configured maximum.
   const appliedTitleSizeDisplay = useMemo(() => {
     const values = Object.values(titleEffectiveTextSizesByItem).filter((value) => Number.isFinite(value));
     if (values.length === 0) {
@@ -124,6 +127,7 @@ const QRCodePrintingDialog = ({
     return `${maxSize.toFixed(1)} mm`;
   }, [titleEffectiveTextSizesByItem, titleMaxTextSize]);
 
+  // Each label can shrink its title differently, so keep measurements per preview item for the settings summary.
   const elements = items.map((item, idx) => {
     const hasHeader = (showManufacturerLogo && !!item.vendor) || (showTitle && !!item.title);
     return (

client/src/pages/printing/spoolSelectModal.tsx

@@ -22,6 +22,7 @@ interface ISpoolCollapsed extends ISpool {
   "filament.material"?: string;
 }
 
+// Flatten filament details so shared table helpers can sort and filter them like top-level spool fields.
 function collapseSpool(element: ISpool): ISpoolCollapsed {
   let filament_name: string;
   if (element.filament.vendor && "name" in element.filament.vendor) {
@@ -37,6 +38,7 @@ function collapseSpool(element: ISpool): ISpoolCollapsed {
   };
 }
 
+// Keep spool picking self-contained: the modal owns selection state and only returns ids once the user confirms.
 const SpoolSelectModal = ({ description, initialSelectedIds, onExport, onPrint }: Props) => {
   const [selectedItems, setSelectedItems] = useState<number[]>(initialSelectedIds ?? []);
   const [showArchived, setShowArchived] = useState(false);
@@ -85,7 +87,7 @@ const SpoolSelectModal = ({ description, initialSelectedIds, onExport, onPrint }
     [tableProps.dataSource],
   );
 
-  // Function to add/remove all filtered items from selected items
+  // Bulk toggles apply to the rows currently loaded in the modal so the action matches the visible table.
   const selectUnselectFiltered = (select: boolean) => {
     setSelectedItems((prevSelected) => {
       const nextSelected = new Set(prevSelected);
@@ -100,14 +102,12 @@ const SpoolSelectModal = ({ description, initialSelectedIds, onExport, onPrint }
     });
   };
 
-  // Handler for selecting/unselecting individual items
   const handleSelectItem = (item: number) => {
     setSelectedItems((prevSelected) =>
       prevSelected.includes(item) ? prevSelected.filter((selected) => selected !== item) : [...prevSelected, item],
     );
   };
 
-  // State for the select/unselect all checkbox
   const isAllFilteredSelected = dataSource.every((spool) => selectedItems.includes(spool.id));
   const isSomeButNotAllFilteredSelected =
     dataSource.some((spool) => selectedItems.includes(spool.id)) && !isAllFilteredSelected;
@@ -189,7 +189,7 @@ const SpoolSelectModal = ({ description, initialSelectedIds, onExport, onPrint }
               onChange={(e) => {
                 setShowArchived(e.target.checked);
                 if (!e.target.checked) {
-                  // Remove archived spools from selected items
+                  // Hidden archived rows should not linger in the selection once the toggle is turned back off.
                   setSelectedItems((prevSelected) =>
                     prevSelected.filter(
                       (selected) => dataSource.find((spool) => spool.id === selected)?.archived !== true,

client/src/pages/vendors/edit.tsx

@@ -102,6 +102,7 @@ export const VendorEdit = () => {
   const printLogoUrlValue = typeof watchedExtra?.print_logo_url === "string" ? watchedExtra.print_logo_url.trim() : "";
   const hasCustomWebLogo = logoUrlValue !== "";
   const hasCustomPrintLogo = printLogoUrlValue !== "";
+  // Build a synthetic vendor record from unsaved form state so the shared preview component works before save.
   const logoPreviewVendor: IVendor = {
     id: 0,
     registered: "",
@@ -165,6 +166,7 @@ export const VendorEdit = () => {
     formProps.form?.setFieldValue(["extra", field], "");
   };
 
+  // Conversion only materializes a runtime print logo when the user already picked a web logo and no print override.
   const convertWebLogoToPrint = async () => {
     if (!canConvertPrintLogo) {
       if (printLogoUrlValue) {

client/src/utils/vendorLogo.ts

@@ -11,6 +11,7 @@ interface LogoMatchScore {
   score: number;
 }
 
+// Vendor logo extras may be stored as JSON strings or legacy plain text; accept either form for previews.
 export function parseExtraString(value: string | undefined): string | undefined {
   if (!value) {
     return undefined;
@@ -62,6 +63,7 @@ function slugFromManifestPath(path: string, type: "web" | "print"): string {
   return base;
 }
 
+// Rank manifest entries conservatively so auto-matching prefers vendor-specific files over generic logo names.
 function scoreLogoPath(name: string, path: string, type: "web" | "print"): number {
   const targetSlug = slugifyVendorName(name);
   if (!targetSlug) {
@@ -110,6 +112,7 @@ function rankPaths(name: string, paths: string[], type: "web" | "print"): LogoMa
     .sort((a, b) => b.score - a.score);
 }
 
+// Only strong matches should auto-populate preview/logo suggestions; weaker matches stay manual choices.
 function findBestPath(name: string, paths: string[], type: "web" | "print"): string | undefined {
   const ranked = rankPaths(name, paths, type);
   if (ranked.length === 0) {
@@ -139,6 +142,7 @@ export function suggestVendorLogoPaths(name: string, manifest: VendorLogoManifes
   return { webPath, printPath };
 }
 
+// Try explicit overrides first, then slug-based runtime paths so local logo packs still resolve without saved URLs.
 export function getVendorLogoCandidates(vendor: IVendor | undefined, usePrintLogo: boolean): string[] {
   if (!vendor) {
     return [];

spoolman/api/v1/vendor.py

@@ -22,6 +22,7 @@
     tags=["vendor"],
 )
 
+# Logo fields are stored in vendor.extra, but the logo workflow owns their schema instead of generic extra-field config.
 RESERVED_VENDOR_EXTRA_KEYS = {"logo_url", "print_logo_url"}
 
 # ruff: noqa: D103
@@ -197,6 +198,7 @@ async def notify_any(
 )
 async def convert_web_logo_to_print(body: VendorLogoConvertRequest) -> VendorLogoConvertResult | JSONResponse:
     try:
+        # Pillow conversion can touch disk and parse image bytes, so run it off the event loop.
         print_logo_url = await asyncio.to_thread(convert_web_logo_to_print_logo, body.logo_url, body.vendor_name)
     except (ValueError, RuntimeError, OSError) as exc:
         return JSONResponse(status_code=400, content=Message(message=str(exc)).model_dump())
@@ -258,6 +260,7 @@ async def create(  # noqa: ANN201
 ):
     if body.extra:
         all_fields = await get_extra_fields(db, EntityType.vendor)
+        # Saved logo paths live alongside extras but bypass generic field validation because they are app-managed.
         extra_to_validate = {k: v for k, v in body.extra.items() if k not in RESERVED_VENDOR_EXTRA_KEYS}
         try:
             validate_extra_field_dict(all_fields, extra_to_validate)
@@ -299,6 +302,7 @@ async def update(  # noqa: ANN201
 
     if body.extra:
         all_fields = await get_extra_fields(db, EntityType.vendor)
+        # Saved logo paths live alongside extras but bypass generic field validation because they are app-managed.
         extra_to_validate = {k: v for k, v in body.extra.items() if k not in RESERVED_VENDOR_EXTRA_KEYS}
         try:
             validate_extra_field_dict(all_fields, extra_to_validate)

spoolman/main.py

@@ -103,6 +103,7 @@ def get_configjs() -> Response:
 @app.get(env.get_base_path() + "/vendor-logos/{asset_path:path}", include_in_schema=False)
 def get_vendor_logo_asset(asset_path: str) -> FileResponse:
     """Serve vendor logo assets from runtime data directory first, then bundled assets."""
+    # Runtime-generated print logos should override bundled defaults without changing client URLs.
     resolved = resolve_vendor_logo_asset(asset_path)
     if resolved is None:
         raise HTTPException(status_code=404, detail="Logo asset not found.")