@yccui/ui

v1.0.0

Published

a month ago

React component library for the Your Cargo Contact APIP platform

0High
0Medium
0Low

faheemumer

react components logistics freight customs ui

@ycc/ui

Professional React component library for logistics and freight management platforms. Extracted from the Your Cargo Contact APIP platform.

Why @ycc/ui

Purpose-built for customs, freight, warehousing, and back-office dashboards.
Fully typed React components with bundled CSS and design-token theming.
Production-ready package output with ESM, CommonJS, declarations, and a live docs site.

Installation

npm install @ycc/ui
yarn add @ycc/ui
pnpm add @ycc/ui

Peer dependencies: react >=18.0.0 and react-dom >=18.0.0.

Quick Start

import '@ycc/ui/styles';
import { ToastProvider, Page, Nav, NavGroup, NavItem, StatCard } from '@ycc/ui';

export function App() {
  return (
    <ToastProvider>
      <Page
        user={{ name: 'Mark', role: 'Administrator' }}
        notificationCount={3}
        nav={(
          <Nav activePage="air">
            <NavGroup label="Freight">
              <NavItem id="air" label="Air Freight" icon="Plane" />
              <NavItem id="sea" label="Sea Freight" icon="Ship" />
            </NavGroup>
          </Nav>
        )}
      >
        <StatCard title="Open Shipments" value="128" change={8.3} trend="up" icon="PackageCheck" />
      </Page>
    </ToastProvider>
  );
}

Package Structure

dist/
  index.js       ESM bundle
  index.cjs      CommonJS bundle
  index.d.ts     TypeScript declarations
  styles.css     Bundled component styles

Components

Each component is exported from @ycc/ui and styled by @ycc/ui/styles.

Page

Full application shell with Sidebar, Header, content, and Footer.

| Prop | Type | Default | Description | |---|---|---|---| | nav | ReactNode | required | Navigation rendered inside the sidebar. | | user | HeaderProps['user'] | undefined | Header user summary. | | notificationCount | number | undefined | Notification badge count. | | children | ReactNode | required | Main page content. | | defaultCollapsed | boolean | false | Initial sidebar state. |

<Page nav={<Nav><NavGroup label="Freight"><NavItem id="air" label="Air Freight" /></NavGroup></Nav>}>
  <StatCard title="Open files" value="128" />
</Page>

Header

Topbar with search, notifications, language select, and user menu.

| Prop | Type | Default | Description | |---|---|---|---| | onMenuToggle | () => void | undefined | Handles menu toggling. | | title | string | undefined | Optional title. | | user | { name: string; role: string; avatar?: string } | undefined | User display data. | | notificationCount | number | undefined | Notification count. | | onLogout | () => void | undefined | Logout callback. |

<Header title="Operations" user={{ name: 'Mark', role: 'Administrator' }} notificationCount={3} />

Footer

Bottom bar with copyright and links.

| Prop | Type | Default | Description | |---|---|---|---| | copyright | string | current year YCC | Copyright text. | | links | Array<{ label: string; href: string }> | [] | Footer links. |

<Footer copyright="© 2026 Your Cargo Contact" links={[{ label: 'Support', href: '/support' }]} />

Sidebar

Collapsible sidebar container.

| Prop | Type | Default | Description | |---|---|---|---| | collapsed | boolean | false | Compact sidebar state. | | onToggle | () => void | undefined | Toggle callback. | | logo | ReactNode | text logo | Logo content. | | children | ReactNode | required | Sidebar body. |

<Sidebar logo="YCC"><Nav>{/* items */}</Nav></Sidebar>

Container

Centered max-width wrapper.

| Prop | Type | Default | Description | |---|---|---|---| | children | ReactNode | required | Content. | | maxWidth | 'sm'|'md'|'lg'|'xl'|'full' | 'lg' | Max-width preset. | | className | string | undefined | Custom class. |

<Container maxWidth="xl">Dashboard content</Container>

Row / Col

12-column flex grid primitives.

| Prop | Type | Default | Description | |---|---|---|---| | Row.children | ReactNode | required | Row content. | | Row.gap | number | 3 | Gap multiplier. | | Col.span | 1..12 | 12 | Base span. | | Col.sm / Col.lg | 1..12 | span | Responsive spans. |

<Row gap={2}><Col span={6}>Air</Col><Col span={6}>Sea</Col></Row>

Grid

CSS grid wrapper.

| Prop | Type | Default | Description | |---|---|---|---| | children | ReactNode | required | Grid items. | | cols | 1|2|3|4|5|6|12 | 2 | Column count. | | gap | number | 3 | Gap multiplier. |

<Grid cols={3}><Card>Air</Card><Card>Sea</Card><Card>Truck</Card></Grid>

PageHeader

Page title, subtitle, and actions slot.

| Prop | Type | Default | Description | |---|---|---|---| | title | string | required | Page title. | | subtitle | string | undefined | Supporting text. | | actions | ReactNode | undefined | Action buttons. |

<PageHeader title="Air Freight" subtitle="Live operations" actions={<Button>Create file</Button>} />

Divider

Horizontal rule with optional label.

| Prop | Type | Default | Description | |---|---|---|---| | label | string | undefined | Center label. | | spacing | 'sm'|'md'|'lg' | 'md' | Vertical spacing. |

<Divider label="Documents" spacing="lg" />

Stack

Vertical flex stack.

| Prop | Type | Default | Description | |---|---|---|---| | children | ReactNode | required | Stack content. | | gap | number | 3 | Gap multiplier. | | align | 'start'|'center'|'end'|'stretch' | 'stretch' | Cross-axis alignment. |

<Stack gap={2}><Badge label="Import" variant="import" /></Stack>

Spacer

Whitespace primitive.

| Prop | Type | Default | Description | |---|---|---|---| | size | number | 4 | Space multiplier. | | axis | 'x'|'y' | 'y' | Direction. |

<Spacer size={6} />

Nav / NavGroup / NavItem

Vertical navigation with active state, groups, icons, and badges.

| Prop | Type | Default | Description | |---|---|---|---| | Nav.children | ReactNode | required | Groups/items. | | Nav.activePage | string | '' | Active item id. | | Nav.collapsed | boolean | false | Compact mode. | | NavItem.badge | string | number | undefined | Item badge. |

<Nav activePage="air"><NavGroup label="Freight"><NavItem id="air" label="Air Freight" icon="Plane" /></NavGroup></Nav>

Breadcrumb

Path trail.

| Prop | Type | Default | Description | |---|---|---|---| | items | Array<{ label: string; href?: string; onClick?: () => void }> | required | Breadcrumb items. | | separator | ReactNode | '/' | Separator. |

<Breadcrumb items={[{ label: 'Home' }, { label: 'Air Freight' }, { label: 'AF-2026-00142' }]} />

Tabs

Controlled tab bar.

| Prop | Type | Default | Description | |---|---|---|---| | tabs | Array<{ id: string; label: string; icon?: string }> | required | Tabs. | | activeTab | string | required | Active id. | | onChange | (id: string) => void | required | Change handler. | | children | ReactNode | undefined | Panel. |

<Tabs tabs={tabs} activeTab={activeTab} onChange={setActiveTab}>Overview</Tabs>

Stepper

Step indicator.

| Prop | Type | Default | Description | |---|---|---|---| | steps | Array<{ label: string; description?: string }> | required | Steps. | | currentStep | number | required | Active zero-based step. |

<Stepper currentStep={1} steps={[{ label: 'Details' }, { label: 'Documents' }]} />

Pagination

Page number controls.

| Prop | Type | Default | Description | |---|---|---|---| | page | number | required | Current page. | | totalPages | number | required | Total pages. | | onChange | (page: number) => void | required | Page callback. | | siblingCount | number | 1 | Adjacent page count. |

<Pagination page={2} totalPages={8} onChange={setPage} />

ContextMenu

Dropdown action menu.

| Prop | Type | Default | Description | |---|---|---|---| | items | Array<{ label: string; icon?: string; onClick: () => void; danger?: boolean; disabled?: boolean }> | required | Menu items. | | trigger | ReactNode | required | Trigger element. |

<ContextMenu trigger={<Button>Actions</Button>} items={[{ label: 'Open', onClick }]} />

Button

Action button.

| Prop | Type | Default | Description | |---|---|---|---| | variant | 'primary'|'secondary'|'ghost'|'danger'|'link' | 'primary' | Visual style. | | size | 'sm'|'md'|'lg' | 'md' | Size. | | loading | boolean | false | Loading state. | | leftIcon / rightIcon | string | undefined | Icon names. |

<Button variant="primary" leftIcon="Plus">Create shipment</Button>

Input, Select, Checkbox, Textarea, Toggle, FormGroup, FileUpload

Core form controls for APIP workflows.

<FormGroup label="Origin port" required>
  <Select options={[{ value: 'ams', label: 'Amsterdam (AMS)' }]} />
</FormGroup>

Radio / RadioGroup

Radio selection controls.

<RadioGroup name="mode" options={[{ value: 'air', label: 'Air Freight' }]} />

DateInput

Styled native date input.

<DateInput defaultValue="2026-06-27" />

SearchInput

Search input with clear button.

<SearchInput value={query} onChange={handleSearch} onClear={() => setQuery('')} />

ScanZone

Barcode/QR scan input area.

<ScanZone active onScan={handleAwbScan} placeholder="Scan AWB barcode" />

Card, StatCard, Table, Badge, Avatar, Tag, Banner, Alert

Primary data display components for dashboard surfaces.

<Card shadow>
  <CardHeader title="Shipment Summary" subtitle="AF-2026-00142" />
  <CardBody>PVG to AMS, 482 kg electronics.</CardBody>
</Card>

Tooltip, Popover, KV, DataList, EmptyState

Detail and contextual display helpers.

<DataList columns={2} items={[{ label: 'Reference', value: 'AF-2026-00142' }]} />

ProgressBar, Donut, TrendSpark, CompareBar, Timeline, Accordion

Operational visualization components with no external chart dependency.

<ProgressBar value={72} label="Warehouse capacity" showPercent />
<TrendSpark data={[4, 8, 7, 10, 12]} />

CopyButton

Copy-to-clipboard button.

| Prop | Type | Default | Description | |---|---|---|---| | value | string | required | Text to copy. | | label | string | 'Copy' | Default label. | | copiedLabel | string | 'Copied' | Success label. |

<CopyButton value="AF-2026-00142" label="Copy reference" />

Toast / useToast

Toast notifications.

function SaveButton() {
  const toast = useToast();
  return <Button onClick={() => toast.success('Shipment saved')}>Save</Button>;
}

Modal, Drawer, Spinner, Skeleton, ConfirmDialog

Feedback and overlay components.

<ConfirmDialog open={open} onClose={close} onConfirm={confirm} message="Delete shipment file?" danger />

Icon

Icon renderer.

| Prop | Type | Default | Description | |---|---|---|---| | name | string | required | Icon name. | | size | number | 16 | SVG size. | | color | string | undefined | CSS color. | | className | string | undefined | Custom class. |

<Icon name="Plane" size={20} />

Design Tokens

@ycc/ui uses CSS custom properties from src/tokens. Import styles once:

import '@ycc/ui/styles';

Override tokens globally:

:root {
  --ycc-accent: #3B82F6;
  --ycc-card: #FFFFFF;
}

Theming

Global theme:

:root { --ycc-accent: #3B82F6; }

Scoped theme:

.customs-dashboard { --ycc-accent: var(--ycc-branch-customs); }

One-off component override:

<Card className="shipment-priority-card">Priority cargo</Card>

Icon Reference

| Icon | Icon | Icon | Icon | |---|---|---|---| | Activity | AlertTriangle | ArrowLeft | ArrowLeftRight | | ArrowRight | BarChart3 | Barcode | Bell | | BellOff | BookOpen | Boxes | Briefcase | | Cable | Calendar | Camera | Check | | CheckCircle2 | ChevronDown | ChevronRight | ClipboardCheck | | Clock | Copy | Cpu | Database | | Download | Euro | FileCheck | FileSpreadsheet | | FileText | Filter | Gauge | Globe | | Hash | HelpCircle | Home | Image | | Landmark | Layers | LayoutDashboard | LayoutGrid | | LeafMark | Link2 | Lock | Mail | | MapPin | Menu | PackageCheck | PackageOpen | | PackageSearch | Pause | Pencil | Plane | | PlaneLanding | PlaneTakeoff | Play | Plug | | Plus | Power | Printer | Radio | | Receipt | RefreshCw | RotateCcw | Route | | Ruler | Scale | ScanLine | ScanSearch | | Search | Send | Server | Settings | | ShieldCheck | Ship | SlidersHorizontal | Split | | Square | Tag | Tags | Trash2 | | TrendingUp | Truck | Upload | Users | | Wallet | Warehouse | Workflow | XCircle | | Zap | | | |

Browser Support

Chrome 90+, Firefox 88+, Safari 14+, Edge 90+.

Contributing

Keep components typed, reusable, documented, and styled only through --ycc-* CSS variables.

License

MIT