@idea-fragments/react-components-zendesk

A comprehensive React component library built on Zendesk Garden components, providing a stable interface for building consistent UIs across IdeaFragments projects.

📋 Table of Contents

• About
• Installation
• Component Groups
• Development
• Using This Library
• Maintaining This Library
• Package Patching
• Building & Publishing
• Contributing

🎯 About

This library is built on the V6 version of the Zendesk Garden React components. Its main purpose is to provide components with stable external interfaces that won't change, regardless of which internal library powers them.

Key Benefits:

• Stable API: Component props remain consistent even if internal implementations change
• Customization: Pre-configured components with IdeaFragments-specific styling and behavior
• Type Safety: Full TypeScript support
• Documentation: Comprehensive Storybook documentation for all components

Current Status: This library uses Zendesk Garden V6. There are plans to upgrade to newer versions at some point in the future.

📦 Installation

As NPM Package (Recommended)

npm install @idea-fragments/react-components-zendesk

🧩 Component Groups

The library is organized into the following component groups:

📝 Forms

Form components including inputs, buttons, selectors, and validation.

Components:

• Button - Primary, secondary, and custom styled buttons
• Checkbox - Checkboxes with label support
• TextField - Text inputs with validation
• DatePickerSelector - Single date picker with dropdown
• DateRangePickerSelector - Date range picker with dropdown
• DateRangeSelectors - Two separate date pickers for start/end dates
• Dropdown - Customizable dropdown component
• And more...

Import:

import {
  Button,
  TextField,
} from "@idea-fragments/react-components-zendesk/forms"

📅 Calendars

Date and time selection components.

Components:

• TinyCalendar - Compact single-date calendar
• TinyDateRangePicker - Compact date range calendar
• MonthPicker - Month selection component
• YearPicker - Year selection component
• MonthYearPicker - Combined month/year picker

Import:

import { TinyCalendar } from "@idea-fragments/react-components-zendesk/calendars"

📊 Tables

Desktop and mobile table components with sorting, pagination, and selection.

Components:

• DesktopTableV2 - Full-featured desktop table
• MobileTableV2 - Mobile-optimized table
• Table - Responsive table that switches between desktop/mobile

Import:

import { Table } from "@idea-fragments/react-components-zendesk/tables"

🎨 Layouts

Layout and navigation components.

Components:

• FlexBox - Flexible layout container
• Sidebar / SidebarV2 - Navigation sidebars
• IconAppBar - Top navigation bar
• Breadcrumbs - Navigation breadcrumbs
• NavigationAction - Navigation links and buttons
• Responsive wrappers: PhonesOnly, TabletsOnly, ComputersOnly

Import:

import {
  FlexBox,
  Sidebar,
} from "@idea-fragments/react-components-zendesk/layouts"

🔄 Loaders

Loading indicators and spinners.

Components:

• TranslucentLoader - Overlay loader
• Spinner - Simple spinner

Import:

import { TranslucentLoader } from "@idea-fragments/react-components-zendesk/loaders"

🎨 Styles

Theme system, typography, and responsive utilities.

Exports:

• useTheme() - Access theme configuration
• SPACINGS - Consistent spacing constants
• FONT_SIZES / FONT_WEIGHTS - Typography constants
• mediaQueries() - Responsive breakpoint helpers
• useDeviceSizeWatcher() - Device size detection hook

Import:

import {
  useTheme,
  SPACINGS,
} from "@idea-fragments/react-components-zendesk/styles"

💬 Tooltips

Tooltip components for contextual information.

Import:

import { Tooltip } from "@idea-fragments/react-components-zendesk/tooltips"

🔧 Utils

Utility functions and helpers.

Import:

import { formatDate } from "@idea-fragments/react-components-zendesk/utils"

🎨 Icons

Icon component wrapper around MDI icons.

Import:

import { Icon } from "@idea-fragments/react-components-zendesk/icon"

🚨 Alerts

Alert and notification components.

Import:

import { Alert } from "@idea-fragments/react-components-zendesk/alert"

🛠️ Development

Prerequisites

• Node.js 16+ and npm
• React 18+
• styled-components 5.3+

Setup

1. Clone the repository:

   git clone https://github.com/idea-fragments/react_components_zendesk.git
   cd react_components_zendesk

2. Install dependencies:

   npm install

3. Start Storybook:

   npm run storybook

Project Structure

react_components_zendesk/
├── src/
│   ├── components/         # Component implementations
│   │   ├── calendars/     # Date/time components
│   │   ├── forms/         # Form components
│   │   ├── layout/        # Layout components
│   │   ├── tables/        # Table components
│   │   └── ...
│   ├── entries/           # Entry points for each module
│   │   ├── forms.ts
│   │   ├── layouts.ts
│   │   └── ...
│   ├── styles/            # Theme and styling utilities
│   ├── hooks/             # Custom React hooks
│   └── utils/             # Utility functions
├── dist/                  # Built output (generated)
├── patches/               # Package patches (patch-package)
├── rollup.config.js       # Build configuration
└── package.json

Development Guidelines

For detailed development guidelines, see CLAUDE.md, which includes:

• Component patterns and best practices
• Responsive design with device size detection
• Styling conventions (FlexBox, spacing, theme usage)
• Alphabetical ordering requirements
• TypeScript patterns

📚 Using This Library

Storybook Documentation

View all components and their usage examples:

npm run storybook

This opens an interactive documentation site at http://localhost:6006 with:

• Live component examples
• Props documentation
• Usage patterns
• Interactive controls

Basic Usage Example

import React, { useState } from "react"
import { Button } from "@idea-fragments/react-components-zendesk/forms"
import { FlexBox } from "@idea-fragments/react-components-zendesk/layouts"
import {
  useTheme,
  SPACINGS,
} from "@idea-fragments/react-components-zendesk/styles"

function MyComponent() {
  const theme = useTheme()
  const [count, setCount] = useState(0)

  return (
    <FlexBox
      gap={SPACINGS.MD}
      withRows>
      <h1>Count: {count}</h1>
      <Button
        onClick={() => setCount(count + 1)}
        primary>
        Increment
      </Button>
    </FlexBox>
  )
}

Responsive Design

Use device size hooks for conditional rendering:

import { useDeviceSizeWatcher } from "@idea-fragments/react-components-zendesk/styles"
import {
  DesktopTableV2,
  MobileTableV2,
} from "@idea-fragments/react-components-zendesk/tables"

function ResponsiveTable(props) {
  const { isSmallComputerOrLarger } = useDeviceSizeWatcher()

  return isSmallComputerOrLarger ? (
    <DesktopTableV2 {...props} />
  ) : (
    <MobileTableV2 {...props} />
  )
}

Or use media queries in styled components:

import styled, { css } from "styled-components"
import { mediaQueries } from "@idea-fragments/react-components-zendesk/styles"

const Container = styled.div`
  display: grid;
  grid-template-columns: 1fr 1fr 1fr;

  ${mediaQueries().forTablets(css`
    grid-template-columns: 1fr 1fr;
  `)}

  ${mediaQueries().forPhones(css`
    grid-template-columns: 1fr;
  `)}
`

Theme Customization

The library uses a theme system. Access theme values with useTheme():

import { useTheme } from "@idea-fragments/react-components-zendesk/styles"
import styled from "styled-components"

const StyledCard = styled.div`
  background: ${({ theme }) => theme.styles.colors.white};
  border: 1px solid ${({ theme }) => theme.styles.colors.grey["300"]};
  border-radius: 8px;
  padding: ${({ theme }) => theme.styles.spacing.md};
`

🔧 Maintaining This Library

Adding New Components

1. Create the component in the appropriate directory under src/components/
2. Create a .stories.tsx file to document the component in Storybook
3. Export the component from the appropriate entry file in src/entries/
4. Follow the guidelines in CLAUDE.md
5. Test in Storybook and build

Modifying Existing Components

1. Make changes to the component file
2. Update the corresponding .stories.tsx file if props changed
3. Test in Storybook
4. Rebuild the library
5. Version bump and publish

Code Quality

The project uses pre-commit hooks to ensure code quality:

# Format code
npm run format

# Lint code
npm run lint

Pre-commit hooks automatically run:

• Prettier formatting
• ESLint linting

Testing Changes

1. Start Storybook to view components:

   npm run storybook

2. Build the library:

   npm run rollup

3. Test in a consuming project:

   # In the consuming project
   npm link ../path/to/react_components_zendesk

🩹 Package Patching

This library uses patch-package to fix issues in third-party dependencies without waiting for upstream fixes.

Current Patches

[email protected]

Issue: React 18 Strict Mode compatibility issue causing infinite scroll calendars to only render 2 months.

Fix: Set this.scrollParent = null in componentWillUnmount to ensure proper cleanup when components are unmounted and remounted in Strict Mode.

Location: patches/react-list+0.8.18.patch

How Patches Work

1. Automatic Application: Patches are automatically applied after npm install via the postinstall script
2. Version Control: Patch files in patches/ directory are committed to the repository
3. Persistence: All developers and CI/CD environments get the same patches

Creating a New Patch

If you need to patch another package:

1. Make your changes directly in node_modules/package-name/
2. Create the patch file:

   npx patch-package package-name

3. Commit the generated patch file in patches/
4. Document the patch in this README

Updating an Existing Patch

1. Modify the file in node_modules/package-name/
2. Regenerate the patch:

   npx patch-package package-name

3. The patch file in patches/ will be updated
4. Commit the changes

Testing Patches

Test that patches apply correctly:

# Remove node_modules
rm -rf node_modules

# Reinstall (patches apply automatically)
npm install

# Verify patches were applied
# Should see: "patch-package: Applied react-list+0.8.18.patch"

Removing a Patch

If a package is updated and the patch is no longer needed:

1. Delete the patch file from patches/
2. Remove the package from node_modules
3. Run npm install

Submitting Patches Upstream

Consider submitting patches to the original package:

# Create an issue draft
npx patch-package package-name --create-issue

This helps the community and may eliminate the need for the patch in future versions.

🏗️ Building & Publishing

Building the Library

The library uses Rollup for bundling. Entry points are defined in rollup.config.js.

Build specific modules:

npm run rollup

This will prompt you to select which modules to build, or you can modify rollup.config.js directly:

modules = [
  "forms",
  "layouts",
  "tables",
  "styles",
  // ... etc
]

Build output goes to the dist/ directory:

dist/
├── forms.js           # Bundled module
├── forms.js.map       # Source map
└── types/
    └── forms.d.ts     # TypeScript definitions

Clean Build

Remove previous build artifacts:

npm run cleanup

Publishing to NPM

1. Ensure all changes are committed
2. Update version in package.json
3. Build the library:

   npm run cleanup
   npm run rollup

4. Publish:

   npm publish

Versioning

Follow Semantic Versioning:

• MAJOR: Breaking changes to component APIs
• MINOR: New components or features (backwards compatible)
• PATCH: Bug fixes and minor improvements

🤝 Contributing

Guidelines

1. Follow the style guide in CLAUDE.md
2. Create Storybook stories for all new components
3. Write TypeScript with proper type definitions
4. Test thoroughly in Storybook and consuming projects
5. Document changes in commit messages

Alphabetical Ordering

This project enforces alphabetical ordering for:

• Import statements (within groups)
• Named imports within destructures
• Type/interface properties
• Function parameters
• Object keys
• JSX props
• React hooks declarations
• Styled component definitions

Pull Request Process

1. Create a feature branch
2. Make your changes
3. Test in Storybook
4. Build the library
5. Submit PR with clear description
6. Wait for review

📝 Scripts Reference

# Development
npm run storybook          # Start Storybook dev server
npm start                  # Start React dev server (legacy)

# Building
npm run rollup             # Build library modules
npm run cleanup            # Remove dist/ directory
npm run build              # Build React app (legacy)

# Code Quality
npm run format             # Format code with Prettier
npm run lint               # Lint code with ESLint

# Testing
npm test                   # Run tests (if configured)

# Storybook
npm run build-storybook    # Build static Storybook site

🔗 Links

• Zendesk Garden Component Library
• Zendesk Garden V6 Documentation
• patch-package Documentation
• IdeaFragments GitHub

⚠️ Important Notes

• Not for public use: This library is primarily for IdeaFragments projects. Use at your own risk.
• React 18 required: This library requires React 18+ for Strict Mode compatibility
• Peer dependencies: Ensure styled-components, React, and MDI icons are installed in your project
• Windows/WSL: If using WSL, you may need to use a Windows Node interpreter for installation (though this may no longer be an issue)

📄 License

MIT

👥 Author

IdeaFragments

Questions or Issues? Open an issue on GitHub