goobs-frontend

# goobs-frontend goobs-frontend is a comprehensive React-based UI component library featuring a custom design system with 100+ components and 260+ icons, built with TypeScript and modern React patterns. The NPM repo is available here - https://www.npmjs.com/package/goobs-frontend This entire repository is written in TypeScript, and there is no need for a separate types installation. ## Storybook See component design and documentation in Storybook available here - https://storybook.technologiesunlimited.net/ ## Integrating goobs-frontend with Next.js This guide explains how to integrate goobs-frontend with a Next.js project. Peer dependencies: `react` ^19 and `react-dom` ^19 (required); `next` ^16 (optional — enables the built-in Link/Image integrations). **Step 1: Install the project** In your Next.js project directory, run the following command to install goobs-frontend #### npm ```bash npm i goobs-frontend ``` #### bun ```bash bun add goobs-frontend ``` #### yarn ```bash yarn add goobs-frontend ``` **Step 2: Import the stylesheet (required)** Component CSS ships as a separate stylesheet — it is not injected by the JS bundle. Import it once at your app root (e.g. `app/layout.tsx`). The self-hosted brand fonts are a separate, optional import: ```tsx import 'goobs-frontend/styles' // required — design tokens + all component CSS import 'goobs-frontend/fonts' // optional — self-hosted brand fonts (Cinzel, Merriweather, Inter, …) ``` **Step 3: Import and use components** goobs-frontend works out of the box with Next.js 16 (Turbopack, Cache Components) — no `transpilePackages` or custom config needed. Just import and use: ```tsx import { CustomButton, DataGrid, Icons } from 'goobs-frontend' ``` A UMD build is also available for script-tag / non-ESM consumers via `goobs-frontend/umd` (global name `GoobsFrontend`; react and react-dom are externalized). ## Component Library Overview goobs-frontend provides 100+ fully-featured React components organized into logical categories. All components are built with TypeScript, custom theming, and responsive design principles. For detailed documentation, examples, and interactive demos, visit our [Storybook](https://storybook.technologiesunlimited.net/). ## Core Component Categories ### 🎨 Layout & Structure - **Paper** - Elevated surface container for content sections - **Panel** - Sectioned surface with `Panel.Header` / `Panel.Body` / `Panel.Footer` subcomponents (also importable directly as `PanelHeader` / `PanelBody` / `PanelFooter`) - **Content** - Dynamic content renderer supporting multiple content types - **WorkspaceFilterShell** - Slot-based scaffold for list/browse workspaces (metrics, nav, filter, and content slots) with a built-in paginator - **FieldGrid** - Responsive form-field layout grid - **Drawer** - Slide-in side panel for navigation and detail views - **Divider** - Visual separators for content organization - **EmptyState** - Consistent empty/no-data placeholder ### 📝 Form Components **Form Engine** - **Form** - Zod-native form engine: schema-driven validation, per-field binding by `name`, and submit gating (`SaveButton`, `useFormField`, `useFieldArray`, `useFieldValues` for dynamic shapes, `useFormContext` / `useOptionalFormContext`) - **FieldShell** - The canonical field wrapper every input builds on — label, error, and required rendering, plus `useFieldBinding` for wiring custom fields into the engine **Text Inputs** - **TextField** - Versatile text input with advanced styling and label positioning - **PasswordField** - Secure password input with show/hide toggle functionality - **SearchBar** - Search input with integrated search icons and styling - **ComplexEditor** - Multi-mode editor (simple, markdown, rich text) with integrated toolbar **Specialized Inputs** - **PhoneNumberField** - Auto-formatting phone number input (+1 xxx-xxx-xxxx) - **USDField** / **MoneyText** - Currency input and display with dollar formatting - **PercentageField** - Percentage input with % symbol and range validation - **ConfirmationCodeInput** - OTP-style multi-digit input with auto-focus progression - **SignatureField** - Canvas signature capture emitting a data-URL value - **Slider** - Range slider input **Number Inputs** - **InternalIncrementNumberField** / **ExternalIncrementNumberField** - Number inputs with increment/decrement controls - **AccountNumber** - Bank account number input with validation - **RoutingNumber** - Bank routing number input with format validation - **CreditCardNumber** - Credit card input with real-time formatting - **CVVField** - Secure CVV input for payment forms **Date & Time** - **DateField** - Date picker with calendar popup and keyboard navigation - **DateRange** - Start/end date selection with range validation - **TimeField** / **TimeRange** - Native time inputs emitting normalized 24-hour `HH:mm` values **Selection Components** - **Dropdown** - Customizable select component with advanced styling - **MultiSelectChip** - Multi-selection dropdown with chip display - **SearchableSimple** / **SearchableHistory** - Real-time filtering dropdowns with autocomplete (history variant remembers recent picks) - **Select** - Native-select styling wrapper - **RadioGroup** - Radio button groups with custom styling and TypeScript support - **Checkbox** - Enhanced checkbox with indeterminate state support - **Switch** - Toggle switch with smooth animations **IPAM & Network Fields** - **IPAddressField** - IP address input with validation - **CIDRField** - CIDR notation input with subnet validation - **SubnetField** / **SupernetField** - Subnet configuration inputs - **VLANField** - VLAN ID input with range validation - **MACAddressField** - MAC address input with auto-formatting ### 🗂️ Data Display - **DataGrid** - Advanced data table with sorting, filtering, pagination, and row management - **Table** - Lightweight table with composable `TableContainer` / `TableHead` / `TableBody` / `TableRow` / `TableCell` subcomponents - **Card** - Compound card family with 25 directly-importable subcomponents (`Card.Header`, `Card.Body`, `Card.Metrics`, `Card.Stats`, `Card.Grid`, and more) - **List** / **ListItemCard** - Flexible lists (`ListItem` / `ListItemIcon` / `ListItemText`; `ListItemCard.Order` / `.Icon` / `.Content` / `.Actions`) - **DetailField** / **DetailGrid** - Read-only labeled value display - **MetricCard** / **MetricsAccordion** - KPI cards and grouped metric panels - **PricingTable** - Specialized pricing comparison table with feature highlights - **ProjectBoard** - Kanban-style board with drag-and-drop task management (plus `InlineAddTask` / `InlineShowTask` task forms) - **BigCalendar** - Month/week/day event calendar with filtering - **Markdown** - Rendered markdown display - **FilterSection** - Faceted filter panel for list/grid views, with a collapsible accordion mode, a standalone `surface` mode, and a `belowSearch` slot ### 🧭 Navigation - **AppBar** - Top application bar - **Tabs** - Horizontal tab navigation with route integration and `underline` or `chips` appearances (standalone `Tab` / `TabPanel` also exported) - **Breadcrumb** - Breadcrumb navigation with custom separators - **Stepper** - Step-by-step process indicator with customizable states - **TreeView** - Hierarchical tree navigation with expand/collapse (`useTreeViewApiRef` / `useTreeViewContext` hooks) - **Pagination** - Page navigation with sibling/boundary control and first/last buttons - **MenuItem** - Menu entry building block for menus and toolbars ### 🎯 Action Components - **CustomButton** / **ButtonGroup** - Highly customizable button with icon support and flexible positioning, plus grouped button rows - **IconButton** - Icon-only buttons with hover states and accessibility - **ToggleButton** / **ToggleButtonGroup** - Toggle buttons with active/inactive states ### 💬 Feedback & Overlays - **Alert** - Contextual alerts with multiple severity levels - **Dialog** - Modal dialogs for complex interactions - **Snackbar** - Toast notifications with severity styling and configurable auto-hide - **StyledTooltip** - Enhanced tooltips with custom positioning and styling - **Popover** - Positioned popup containers ### 🔧 Utility Components - **Accordion** - Collapsible content sections with smooth animations - **Badge** - Notification badges with custom positioning - **Chip** - Compact information chips with delete functionality - **Avatar** - Themed circular avatar container for icon, text, or image children - **ProgressBar** - Progress indicators with customizable styling - **CodeCopy** - Syntax-highlighted code blocks with one-click copying - **QRCodeComponent** - QR code renderer with an MFA-setup flow (optional confirmation-code input and verify gate) - **TransferList** - Dual-list component for moving items between collections ### 🎨 Design & Animation - **Typography** - Text component with the brand font stack (Cinzel headings, Merriweather and Crimson Text body variants) - **SacredGlyphFrame** - Ornamental hieroglyph-framed surface for the sacred theme - **Fade**, **Slide**, **Zoom** - Smooth transition components for enhanced UX ### 🏗️ Advanced Components - **CustomToolbar** - Flexible toolbar with multiple sections and responsive behavior - **FormDataGrid** / **FormProjectBoard** - DataGrid and ProjectBoard wired into the Form engine - **FileDropzone** - Drag-and-drop file upload surface ### 🧰 Utilities - **alpha(color, opacity)** - Hex/RGB → rgba color helper - **keyframes** / **css** / **commonKeyframes** - Runtime `@keyframes` helpers, including the sacred glow/float/rotate presets - **SACRED_GLYPHS** - The 24-glyph Egyptian-hieroglyph set behind the sacred theme's ornamentation ### 📱 Mobile-First Design All components are built with mobile-first responsive design principles, ensuring optimal performance across desktop, tablet, and mobile devices. ### 🎨 Comprehensive Icon Library 260+ carefully crafted icons, each importable via the `Icons` namespace (e.g. `Icons.AddIcon`), covering: - Navigation (arrows, chevrons, menu controls) - Actions (add, delete, edit, save, settings) - Communication (email, phone, notifications) - Business (payment, store, analytics) - Technology (code, devices, security, networking) - Status indicators (success, error, warning, info) ## Key Features ### 🔧 Customization - **Three built-in themes** - `sacred`, `light`, and `dark` via each component's `styles.theme` prop (defaults are per-component: core surfaces and form fields default to `sacred`; most feedback/utility components and all icons default to `light`) - **Token-driven styling** - CSS Modules on a shared `--goobs-*` design-token layer (import `goobs-frontend/styles`; brand fonts via `goobs-frontend/fonts`) - **Component Variants** - Multiple pre-built variants for common use cases ### 📋 Developer Experience - **Full TypeScript Support** - Complete type definitions with IntelliSense - **Comprehensive Documentation** - Interactive Storybook with live examples - **Consistent API** - Predictable prop patterns across all components ### ♿ Accessibility & Performance - **ARIA Compliance** - Full accessibility support with proper ARIA labels - **Keyboard Navigation** - Complete keyboard support for all interactive components - **Performance Optimized** - Lazy loading, code splitting, and optimized bundle sizes ### 🚀 Modern React Patterns - **Hooks-Based** - Built with modern React hooks and functional components - **Form Integration** - A built-in zod-native `<Form>` engine binds any field by `name` (no external form library required) _For complete component documentation, interactive examples, and implementation guides, visit the [Storybook documentation](https://storybook.technologiesunlimited.net/)._ ### Feedback and Contributions I welcome feedback and contributions of all kinds: - Issues: Report bugs or request features via GitHub Issues. - Pull Requests: Fork, create a branch, and open a PR for review. - Custom Requests: If you need special features or want these components ported to a different design system, reach out. ### License goobs-frontend is licensed under the MIT License. ### Contact For questions, support, or further details, please contact Matthew Goluba Email: mkgoluba@technologiesunlimited.net Enjoy building with goobs-frontend!