Wine Explorer is a Strudel Kit demo that showcases a client-side data exploration workflow for the UCI Wine Quality datasets. The application is built with React, TypeScript, and Vite and demonstrates how to deliver rapid dataset inspection, lightweight analytics, and accessibility-first interactions without relying on a backend service.
- Switch between red and white wine datasets with cached loading and retryable error handling.
- Filter by alcohol, pH, and volatile acidity using keyboard-accessible range sliders that keep URL state in sync.
- Explore interactive histograms and scatter plots powered by Plotly to compare feature distributions and relationships.
- Review dataset metadata, citation details, and filtered record counts in an info panel optimized for assistive technology.
- Ship as a static, client-only bundle that runs entirely in the browser and can be deployed to any static host.
- Node.js ^18.18.0 or >=20.0.0 (matches the
enginesfield) - npm 9+
git clone https://github.com/superbloom/wine-explorer.git
cd wine-explorer
npm installnpm run devThe Vite dev server runs on http://localhost:5173 by default. You can configure the port by setting the VITE_PORT environment variable:
VITE_PORT=8080 npm run devEnvironment variables can also be defined in a .env file. See .env.example for available options.
npm test— runs the Vitest suite with thejsdomenvironment and shared setup intests/setup.ts.npm run cy:open— opens the Cypress runner for exploratory end-to-end testing.npm run cy:test— runs the Cypress suite headlessly for CI.npm run lint/npm run lint:fix— lints the project with the Airbnb TypeScript configuration.npm run prettier/npm run prettier:fix— checks or formats code according to the project Prettier rules.npm run style:all— type-checks, lints, and runs Prettier to mimic the repository gate before committing.
Vitest supports watch mode via npm test -- --watch when iterating on new units.
npm run buildThe build step runs TypeScript type-checking and emits an optimized static bundle into dist/. Preview the production build locally before deploying:
npm run preview- Ensure
homepageinpackage.jsonorVITE_BASE_URLmatches the target path when deploying behind a subdirectory. npm run buildto generate the latest bundle.- Publish the
dist/directory to your static host.
For GitHub Pages the project ships with a helper script:
npm run deployThis command pushes the built dist/ folder to the gh-pages branch using the gh-pages CLI with history preservation (-e demo).
.
├── public/ # Static assets, including winequality CSV datasets
├── src/
│ ├── components/ # Dataset selector, filter panel, visualization suite, info panel, layout primitives
│ ├── context/ # React contexts for wine data and accessibility announcements
│ ├── hooks/ # Reusable hooks (e.g., delayed spinners)
│ ├── pages/ # Routed page shells used by TanStack Router
│ ├── types/ # Shared TypeScript interfaces for wine data and filters
│ └── utils/ # Data manager, error helpers, and filtering utilities
├── tests/ # Vitest setup and helpers
├── cypress/ # Cypress end-to-end specs and fixtures
├── docs/ # Extended architecture, component, and workflow documentation
└── vite.config.ts # Vite and Vitest configuration
Developer documentation lives in docs/. Start with docs/README.md for an index that links to architecture, component, workflow, and API references.
Contributions are welcome! Begin with CONTRIBUTING.md for branching workflow, code standards, and review expectations, and review CODE_OF_CONDUCT.md for community guidelines. Open an issue before large changes so maintainers can help scope the work.
Wine Explorer inherits the STRUDEL project license. Review the full terms in LICENSE, published by Lawrence Berkeley National Laboratory on behalf of the STRUDEL project.
- UCI Machine Learning Repository for the red and white wine quality datasets (DOI: 10.24432/C56S3T).
- The STRUDEL project and Superbloom for the design system, task flow templates, and engineering starter kit used to deliver this demo.