Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Notion Table View and Filters

A full-stack application implementing Notion table view UI with advanced filtering capabilities, built with React, TypeScript, Node.js, and Docker for easy deployment.

πŸš€ Quick Start with Docker

Prerequisites:

  • Docker and Docker Compose
  • Notion API key and Database ID

Setup Steps:

  1. Clone and setup environment:
git clone <repository-url>
cd notion-table-view-filters
cp server/.env.example server/.env
  1. Add your Notion credentials to server/.env:
NOTION_SECRET=your_notion_integration_token_here
NOTION_DATABASE_ID=your_notion_database_id_here
  1. Start the application:
make dev
# Or: docker-compose up --build
  1. Access the app:

🐳 Docker Commands

# Build and start all services
make dev

# Stop services
make down

# View logs
make logs

# Clean up everything
make clean

# Run tests
make test

πŸ“‹ Features

Table View UI

  • Responsive table display with modern design
  • Column sorting functionality
  • Drag-and-drop column rearrangement
  • Column resizing for optimal viewing
  • Loading states and error handling

Advanced Filter System

  • Single Filters: Simple filter conditions for individual properties
  • Compound Filters: Advanced filtering with logical operators
    • AND/OR Operations: Combine multiple filter conditions
    • NOT Operations: Negate filter conditions with validation
    • Nested Groups: Create complex filter hierarchies (configurable depth)

Property Type Support

  • Checkbox (is, is not)
  • Date (equals, before, after, between, is empty, is not empty)
  • Number (=, β‰ , >, <, β‰₯, ≀, is empty, is not empty)
  • Text/Rich Text (is, is not, contains, does not contain, starts with, ends with, is empty, is not empty)
  • Select/Multi-select (contains, does not contain, is empty, is not empty)
  • Status (is, is not)

NOT Operator Implementation

  • Direct Negation: NOT (property = "value") β†’ property != "value"
  • Complex Logic: NOT (A AND B) β†’ (NOT A) OR (NOT B)
  • Validation System: Real-time error detection for unsupported operators
  • User-friendly Messages: Clear error descriptions

Form Validation

  • Real-time validation with error messages
  • Smart button disabling based on validation state
  • Required field validation for all filter inputs
  • React Hook Form integration

πŸ›  Tech Stack

Frontend

  • React 19 with TypeScript
  • Vite for fast development and building
  • Tailwind CSS for utility-first styling
  • React Hook Form for form state management
  • React DnD Kit for drag-and-drop functionality
  • React Testing Library for component testing

Backend

  • Node.js with TypeScript
  • Express.js REST API
  • @notionhq/client for Notion API integration
  • CORS enabled for frontend communication

Development Tools

  • Docker for containerization
  • Docker Compose for multi-service orchestration
  • Jest for testing
  • ESLint for code linting
  • Make for command shortcuts

πŸ“ Project Structure

β”œβ”€β”€ src/                    # Frontend React app
β”‚   β”œβ”€β”€ components/         # React components
β”‚   β”‚   β”œβ”€β”€ filters/        # Filter system components
β”‚   β”‚   └── ...             # Other UI components
β”‚   β”œβ”€β”€ types/              # TypeScript type definitions
β”‚   β”œβ”€β”€ utils/              # Utility functions
β”‚   └── App.tsx             # Main app component
β”œβ”€β”€ server/                  # Backend Express server
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ index.ts        # Express server entry point
β”‚   β”‚   └── types/          # Backend type definitions
β”‚   β”œβ”€β”€ Dockerfile          # Backend Docker configuration
β”‚   β”œβ”€β”€ .env.example        # Environment variables template
β”‚   └── package.json        # Backend dependencies
β”œβ”€β”€ docker-compose.yml       # Docker Compose configuration
β”œβ”€β”€ Dockerfile              # Frontend Docker configuration
β”œβ”€β”€ Makefile                # Command shortcuts
└── README.md               # This file

πŸ”§ Configuration

Environment Variables

Create server/.env based on server/.env.example:

# Required: Get from https://www.notion.so/my-integrations
NOTION_SECRET=your_notion_integration_token
NOTION_DATABASE_ID=your_notion_database_id

# Optional
PORT=3001
HOST=0.0.0.0
NODE_ENV=production

Getting Notion API Credentials

  1. Create Integration:

  2. Share Database:

    • Open your Notion database
    • Click "..." β†’ "Connections"
    • Add your integration
  3. Get Database ID:

    • Open your Notion database
    • Copy the ID from the URL (the part after notion.so/ and before ?v=)

πŸ§ͺ Testing

Running Tests

# Frontend tests
npm test

# Backend tests (if available)
cd server && npm test

# Test with Docker
make test

Test Coverage

  • Unit Tests: Core utility functions for NOT operator validation
  • Component Tests: Filter components with React Testing Library
  • Integration Tests: Form validation and user interactions

πŸš€ Deployment

Docker Deployment (Recommended)

# Production deployment
make deploy

# Or manually:
docker-compose -f docker-compose.yml up --build -d

Alternative Deployments

Frontend Only

  • Vercel: vercel --prod
  • Netlify: Drag dist folder to netlify.com/drop
  • GitHub Pages: npm run deploy

Backend Only

  • Railway: railway up
  • Render: Connect GitHub repo
  • Heroku: Git push to Heroku

🎯 Advanced Features

Filter Processing

Filter Flattening

  • Handles filters with more than 2 nesting levels
  • Converts deeply nested structures into manageable forms
  • Configurable depth (default: 2 levels)

Filter Splitting

  • Splits complex filters into multiple simpler groups
  • Prevents Notion API limit violations
  • Chunked processing (default: 10 filters per group)

Filter Optimization

  • Combines flattening and splitting based on complexity
  • Smart algorithms for optimal processing
  • Configurable options for customization

Performance Optimizations

  • Container health checks for reliability
  • Non-root Docker users for security
  • Optimized Docker layers for faster builds
  • CORS configuration for seamless frontend-backend communication

πŸ” API Endpoints

Backend Server (Port 3001)

  • GET /structure - Get database structure and properties
  • POST /query - Query database with filters and sorting
  • OPTIONS / - CORS preflight handling

Request Examples

// Get database structure
GET http://localhost:3001/structure

// Query with filters
POST http://localhost:3001/query
{
  "filter": {
    "and": [
      {
        "property": "Status",
        "select": {
          "equals": "Done"
        }
      }
    ]
  },
  "sorts": [
    {
      "property": "Created",
      "direction": "descending"
    }
  ],
  "page_size": 50
}

πŸ› Troubleshooting

Common Issues

  1. "Must define NOTION_SECRET and NOTION_DATABASE_ID"

    • Ensure you created server/.env from server/.env.example
    • Check that your Notion integration has access to the database
  2. Frontend can't reach backend

    • Ensure both containers are running: docker-compose ps
    • Check logs: make logs
  3. Build errors

    • Clean and rebuild: make clean && make dev
    • Check Node.js version compatibility

Docker Issues

# Check container status
docker-compose ps

# View logs
docker-compose logs [service-name]

# Restart services
docker-compose restart

# Clean everything
make clean

🀝 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

πŸ“„ License

ISC

πŸ™ Notes for Reviewers

Key Implementation Highlights

  • Full Docker Integration: Complete containerization with health checks and security best practices
  • Advanced NOT Operator: Complex negation logic with comprehensive validation
  • Filter Optimization: Automatic flattening and splitting for large queries
  • Type Safety: Full TypeScript coverage across frontend and backend
  • Testing: Comprehensive test suite with Jest and React Testing Library
  • Production Ready: Environment variable management, error handling, and deployment configurations

Technical Decisions

  • Used React Hook Form for superior form state management
  • Implemented custom filter flattening to handle Notion API limitations
  • Added Makefile for simplified Docker operations
  • Structured monorepo-style with separate frontend and backend
  • Implemented non-root Docker users for security

Performance Considerations

  • Docker layer optimization for faster builds
  • Filter chunking to prevent API timeouts
  • Lazy loading and code splitting opportunities
  • Health checks for service reliability

This application demonstrates advanced React development, API integration, and production deployment practices.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages