Shipping Carriers Package

A beautiful, reusable shipping carriers table component built with React, TypeScript, and TanStack Table (React Table v8).

Features

• 🎨 Modern UI - Clean and professional design with Tailwind CSS
• 🔍 Global Search - Search across all columns instantly
• 📊 Sortable Columns - Click any column header to sort
• 👁️ Column Visibility - Show/hide columns as needed
• 📱 Responsive - Works on all screen sizes
• 🎯 Pagination - Built-in pagination with customizable page sizes
• ⚡ TypeScript - Full type safety
• 🎭 Customizable - Easy to customize and extend
• ✨ Modal Dialogs - Built-in modals for add/edit/delete operations
• 🔌 API Integration - Ready-to-use API client for .NET backends
• ✅ Form Validation - Built-in validation for required fields
• 🗑️ Delete Confirmation - Safe delete with confirmation dialog

Installation

npm install shipping-carriers-package
# or
yarn add shipping-carriers-package

Peer Dependencies

Make sure you have these installed:

npm install react react-dom

Usage

Basic Usage (Table Only)

import { ShippingCarriersTable } from "shipping-carriers-package";
import type { ShippingCarrier } from "shipping-carriers-package";

const carriers: ShippingCarrier[] = [
  {
    id: "1",
    name: "FEDEX",
    userName: "admin",
    clientKey: "key123",
    secretKey: "secret123",
    token: "token123",
    url: "https://api.fedex.com",
    createdDate: new Date("2023-03-16T11:16:00"),
    createdBy: "John Doe",
    updatedDate: new Date("2023-05-02T09:23:00"),
    updatedBy: "Jane Smith",
    status: "Active",
  },
  // ... more carriers
];

function App() {
  const handleAdd = () => {
    console.log("Add new carrier");
  };

  const handleEdit = (carrier: ShippingCarrier) => {
    console.log("Edit carrier:", carrier);
  };

  const handleDelete = (carrier: ShippingCarrier) => {
    console.log("Delete carrier:", carrier);
  };

  return (
    <ShippingCarriersTable
      carriers={carriers}
      onAdd={handleAdd}
      onEdit={handleEdit}
      onDelete={handleDelete}
    />
  );
}

Complete Usage with Modals and API

"use client";

import { useState, useEffect } from "react";
import {
  ShippingCarriersTable,
  ShippingCarrierModal,
  DeleteConfirmationModal,
  shippingCarriersApi,
  type ShippingCarrier,
} from "shipping-carriers-package";

function App() {
  const [carriers, setCarriers] = useState<ShippingCarrier[]>([]);
  const [loading, setLoading] = useState(false);

  // Modal states
  const [isAddEditModalOpen, setIsAddEditModalOpen] = useState(false);
  const [isDeleteModalOpen, setIsDeleteModalOpen] = useState(false);
  const [modalMode, setModalMode] = useState<"add" | "edit">("add");
  const [selectedCarrier, setSelectedCarrier] =
    useState<ShippingCarrier | null>(null);

  // Fetch carriers from API
  useEffect(() => {
    fetchCarriers();
  }, []);

  const fetchCarriers = async () => {
    setLoading(true);
    try {
      const data = await shippingCarriersApi.getAll();
      setCarriers(data);
    } catch (error) {
      console.error("Error fetching carriers:", error);
    } finally {
      setLoading(false);
    }
  };

  const handleAdd = () => {
    setModalMode("add");
    setSelectedCarrier(null);
    setIsAddEditModalOpen(true);
  };

  const handleEdit = (carrier: ShippingCarrier) => {
    setModalMode("edit");
    setSelectedCarrier(carrier);
    setIsAddEditModalOpen(true);
  };

  const handleDelete = (carrier: ShippingCarrier) => {
    setSelectedCarrier(carrier);
    setIsDeleteModalOpen(true);
  };

  const handleSaveCarrier = async (carrierData) => {
    if (modalMode === "add") {
      const newCarrier = await shippingCarriersApi.create(carrierData);
      setCarriers((prev) => [...prev, newCarrier]);
    } else if (selectedCarrier) {
      const updated = await shippingCarriersApi.update(selectedCarrier.id, {
        id: selectedCarrier.id,
        ...carrierData,
      });
      setCarriers((prev) =>
        prev.map((c) => (c.id === updated.id ? updated : c))
      );
    }
  };

  const handleConfirmDelete = async () => {
    if (!selectedCarrier) return;
    await shippingCarriersApi.delete(selectedCarrier.id);
    setCarriers((prev) => prev.filter((c) => c.id !== selectedCarrier.id));
  };

  return (
    <div>
      <ShippingCarriersTable
        carriers={carriers}
        onAdd={handleAdd}
        onEdit={handleEdit}
        onDelete={handleDelete}
      />

      {/* Add/Edit Modal */}
      <ShippingCarrierModal
        isOpen={isAddEditModalOpen}
        onClose={() => setIsAddEditModalOpen(false)}
        onSave={handleSaveCarrier}
        carrier={selectedCarrier}
        mode={modalMode}
      />

      {/* Delete Confirmation Modal */}
      <DeleteConfirmationModal
        isOpen={isDeleteModalOpen}
        onClose={() => setIsDeleteModalOpen(false)}
        onConfirm={handleConfirmDelete}
        itemName={selectedCarrier?.name}
      />
    </div>
  );
}

API Configuration

Setup for .NET Backend

1. Create a .env.local file in your project root:

NEXT_PUBLIC_API_URL=https://localhost:7000/api

2. Update the URL to match your .NET API endpoint.

For detailed .NET API setup instructions, including controller implementation examples, see API_SETUP.md.

Available API Methods

// Get all carriers
const carriers = await shippingCarriersApi.getAll();

// Get single carrier by ID
const carrier = await shippingCarriersApi.getById("carrier-id");

// Create new carrier
const newCarrier = await shippingCarriersApi.create({
  name: "FedEx",
  userName: "[email protected]",
  status: "Active",
});

// Update carrier
const updated = await shippingCarriersApi.update("carrier-id", {
  id: "carrier-id",
  name: "FedEx Updated",
  status: "Active",
});

// Delete carrier
await shippingCarriersApi.delete("carrier-id");

// Update status only
const statusUpdated = await shippingCarriersApi.updateStatus(
  "carrier-id",
  "Inactive"
);

Component API

ShippingCarriersTable Props

| Prop | Type | Description | | ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------------ | | carriers | ShippingCarrier[] | Array of shipping carrier data (required) | | onAdd | () => void | Callback when "Add Shipping Carrier" button is clicked | | onEdit | (carrier: ShippingCarrier) => void | Callback when edit button is clicked | | onDelete | (carrier: ShippingCarrier) => void | Callback when delete is triggered | | onStatusChange | (carrier: ShippingCarrier, newStatus: 'Active' \| 'Inactive') => void | Callback when status changes |

ShippingCarrierModal Props

| Prop | Type | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | isOpen | boolean | Whether the modal is open (required) | | onClose | () => void | Callback when modal is closed (required) | | onSave | (carrier: Omit<ShippingCarrier, 'id' \| 'createdDate' \| 'createdBy' \| 'updatedDate' \| 'updatedBy'>) => Promise<void> | Callback when form is submitted (required) | | carrier | ShippingCarrier \| null | Carrier to edit (null for add mode) | | mode | 'add' \| 'edit' | Modal mode (required) |

DeleteConfirmationModal Props

| Prop | Type | Description | | ----------- | --------------------- | -------------------------------------------- | | isOpen | boolean | Whether the modal is open (required) | | onClose | () => void | Callback when modal is closed (required) | | onConfirm | () => Promise<void> | Callback when delete is confirmed (required) | | title | string | Modal title (optional) | | message | string | Confirmation message (optional) | | itemName | string | Name of item being deleted (optional) |

ShippingCarrier Type

interface ShippingCarrier {
  id: string;
  name: string;
  userName?: string;
  clientKey?: string;
  secretKey?: string;
  token?: string;
  url?: string;
  createdDate: Date;
  createdBy?: string;
  updatedDate: Date;
  updatedBy?: string;
  status: "Active" | "Inactive";
}

Exported Components and Types

// Components
export { ShippingCarriersTable } from "shipping-carriers-package";
export { ShippingCarrierModal } from "shipping-carriers-package";
export { DeleteConfirmationModal } from "shipping-carriers-package";

// UI Components (for customization)
export { Button } from "shipping-carriers-package";
export { Badge } from "shipping-carriers-package";
export { Input } from "shipping-carriers-package";
export { Select } from "shipping-carriers-package";
export { Modal } from "shipping-carriers-package";

// API
export { shippingCarriersApi } from "shipping-carriers-package";
export { useShippingCarriersApi } from "shipping-carriers-package";

// Types
export type { ShippingCarrier } from "shipping-carriers-package";
export type { ShippingCarrierTableProps } from "shipping-carriers-package";
export type { CreateShippingCarrierDto } from "shipping-carriers-package";
export type { UpdateShippingCarrierDto } from "shipping-carriers-package";

Styling

This package uses Tailwind CSS. Make sure your project has Tailwind CSS configured. The component uses standard Tailwind classes and will inherit your project's Tailwind configuration.

Development

To run the demo locally:

# Clone the repository
git clone <repository-url>

# Install dependencies
npm install

# Run development server
npm run dev

Open http://localhost:3000 to view the demo.

Building the Package

npm run build:package

This will compile the TypeScript files to the dist folder.

Publishing

# Update version in package.json
npm version patch|minor|major

# Publish to npm
npm publish

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.