claritykit-svelte
Version:
A comprehensive Svelte component library focused on accessibility, ADHD-optimized design, developer experience, and full SSR compatibility
489 lines (385 loc) • 15.6 kB
Markdown
# ClarityKit - Svelte Component Library
[](https://badge.fury.io/js/claritykit-svelte)
[](https://github.com/warkrismagic/ClarityKit_svelte/actions/workflows/ci.yml)
[](https://github.com/warkrismagic/ClarityKit_svelte/actions/workflows/storybook.yml)
[](https://codecov.io/gh/warkrismagic/ClarityKit_svelte)
[](https://github.com/warkrismagic/ClarityKit_svelte/actions/workflows/chromatic.yml)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.w3.org/WAI/WCAG21/quickref/?currentsidebar=%23col_overview&levels=aaa)
[](./docs/therapeutic-design-principles.md)
A comprehensive Svelte component library focused on accessibility, ADHD-optimized design, and exceptional developer experience. Built with Svelte 5 and TypeScript, ClarityKit provides a complete toolkit for building modern, inclusive web applications with **187+ components** across 12 categories.
> **NEW in v1.6.0**: Research Components, Enhanced Data Visualization, Advanced Accessibility Features, and AI Integration
## ✨ Features
- 🎯 **ADHD-Optimized Design**: Components designed with cognitive load reduction in mind
- ♿ **Accessibility First**: WCAG 2.1 AA compliant with comprehensive screen reader support
- 🏗️ **SSR Ready**: Full server-side rendering compatibility with SvelteKit
- 🎨 **Themeable**: Built-in light/dark mode with customizable design tokens
- 📱 **Responsive**: Mobile-first design with flexible layouts
- 🔧 **TypeScript**: Fully typed API with excellent IntelliSense support
- 🌳 **Tree Shakeable**: Import only what you need for optimal bundle size
- 📖 **Well Documented**: Comprehensive Storybook documentation with examples
## 📦 Installation
```bash
npm install claritykit-svelte
```
```bash
pnpm add claritykit-svelte
```
```bash
yarn add claritykit-svelte
```
## 🚀 Quick Start
### Basic Usage
```svelte
<script>
import { Button, Card, Alert } from 'claritykit-svelte';
import 'claritykit-svelte/styles/tokens.css';
import 'claritykit-svelte/styles/components.css';
</script>
<Card>
<h2>Welcome to ClarityKit</h2>
<p>A beautiful, accessible component library for Svelte.</p>
<Button variant="primary" onclick={() => alert('Hello!')}>
Get Started
</Button>
</Card>
```
### With SvelteKit
```javascript
// app.html or +layout.svelte
import 'claritykit-svelte/styles/tokens.css';
import 'claritykit-svelte/styles/components.css';
```
### Individual Component Imports
```svelte
<script>
// Tree-shakeable imports
import { Button } from 'claritykit-svelte';
import { Card } from 'claritykit-svelte';
import type { ButtonVariant } from 'claritykit-svelte';
</script>
```
## 🎨 Styling
ClarityKit uses CSS custom properties for theming. Import the base styles and customize as needed:
```css
/* Import base styles */
@import 'claritykit-svelte/styles/tokens.css';
@import 'claritykit-svelte/styles/components.css';
/* Customize theme */
:root {
--ck-color-primary: #3b82f6;
--ck-color-secondary: #6366f1;
--ck-border-radius: 8px;
}
```
## Component Categories
**187+ Components Across 12 Categories**
- **Primitives**: Button, Input, Checkbox, Radio, Switch, Avatar, Loader, StatusDot, etc.
- **Layout**: Container, Grid, Card, Modal, Sidebar, Popover, GalleryView, ListView, etc.
- **Feedback**: Alert, Toast, StatusIndicator, LoadingSpinner, Progress indicators, etc.
- **Data Visualization**: Charts (Line, Bar, Area, Pie, Scatter, Network), KPI cards, Metrics, Dashboard widgets, etc.
- **Form**: Enhanced Select with search/multi-select/async loading, FormField, Textarea, DatePicker, validation, etc.
- **Navigation**: Tabs, Badge, CommandPalette, WorkspaceSelector, Breadcrumbs, etc.
- **Agent & AI**: AgentCard, PlanCard, ChatThread, AgentLogView, AISettings, CollaborativeWorkspace, etc.
- **Knowledge Management**: BlockEditor, CollaborativeBlockEditor, KnowledgeGraph, SemanticTagger, etc.
- **Research**: **NEW** CitationFormatter, PaperMetadataCard, ResearchDiscoveryPanel, PaperIngestionProgress, etc.
- **BMS**: Business Management System components for workflow automation and integration
- **Therapeutic**: ADHD-specific components like CrisisModeToggle, MoodTracker, EnergyLevelIndicator, etc.
- **Interactive**: Gantt charts, Task management, Kanban boards, etc.
## 🧠 Personal Knowledge Management (PKM)
ClarityKit provides a complete suite of PKM components designed for building modern knowledge management applications, note-taking tools, and collaborative platforms.
### Core PKM Components
#### BlockEditor
A rich TipTap-based block editor with AI assistance capabilities:
```svelte
<script>
import { BlockEditor } from 'claritykit-svelte';
let content = '<p>Start typing...</p>';
</script>
<BlockEditor
bind:content
placeholder="What's on your mind?"
enableAI={true}
onSave={(html) => console.log('Saved:', html)}
/>
```
#### CollaborativeBlockEditor
Real-time collaborative editing powered by Hocuspocus and Yjs:
```svelte
<script>
import { CollaborativeBlockEditor, HocuspocusCollaborationProvider } from 'claritykit-svelte';
const provider = new HocuspocusCollaborationProvider({
url: 'wss://your-collab-server.com',
name: 'document-123'
});
</script>
<CollaborativeBlockEditor
{provider}
userName="John Doe"
userColor="#3b82f6"
enablePresenceIndicators={true}
/>
```
#### KnowledgeGraph
Interactive knowledge graphs using Cytoscape.js:
```svelte
<script>
import { KnowledgeGraph } from 'claritykit-svelte';
const nodes = [
{ id: 'concept1', label: 'Machine Learning', category: 'technology' },
{ id: 'concept2', label: 'Neural Networks', category: 'technology' },
{ id: 'concept3', label: 'Deep Learning', category: 'technology' }
];
const edges = [
{ source: 'concept1', target: 'concept2', relationship: 'includes' },
{ source: 'concept2', target: 'concept3', relationship: 'enables' }
];
</script>
<KnowledgeGraph
{nodes}
{edges}
layout="cose"
enablePhysics={true}
onNodeClick={(node) => console.log('Clicked:', node)}
/>
```
#### SemanticTagger
AI-powered semantic tagging and concept extraction:
```svelte
<script>
import { SemanticTagger } from 'claritykit-svelte';
let selectedTags = [];
const concepts = [
{ id: 1, term: 'machine learning', definition: 'AI technique for pattern recognition' },
{ id: 2, term: 'neural network', definition: 'Computing system inspired by biological neural networks' }
];
</script>
<SemanticTagger
{concepts}
bind:selectedTags
enableAIExtraction={true}
onTagCreate={(tag) => console.log('New tag:', tag)}
/>
```
#### MaterialViewTable
Advanced table component with filtering, sorting, and views:
```svelte
<script>
import { MaterialViewTable } from 'claritykit-svelte';
const data = [
{ id: 1, title: 'Research Paper', type: 'document', tags: ['AI', 'ML'] },
{ id: 2, title: 'Meeting Notes', type: 'note', tags: ['meeting', 'planning'] }
];
const columns = [
{ key: 'title', label: 'Title', sortable: true },
{ key: 'type', label: 'Type', filterable: true },
{ key: 'tags', label: 'Tags', render: 'tags' }
];
</script>
<MaterialViewTable
{data}
{columns}
searchable={true}
exportable={true}
viewModes={['table', 'card', 'list']}
/>
```
#### DatabaseView
Notion-style database views with multiple display modes:
```svelte
<script>
import { DatabaseView } from 'claritykit-svelte';
const data = [
{ id: 1, name: 'Project Alpha', status: 'active', priority: 'high' },
{ id: 2, name: 'Project Beta', status: 'planning', priority: 'medium' }
];
</script>
<DatabaseView
{data}
view="kanban"
groupBy="status"
enableInlineEditing={true}
onUpdate={(item) => console.log('Updated:', item)}
/>
```
#### RichTextToolbar
Customizable toolbar for rich text editing:
```svelte
<script>
import { RichTextToolbar } from 'claritykit-svelte';
let editor; // TipTap editor instance
</script>
<RichTextToolbar
{editor}
tools={['bold', 'italic', 'link', 'image', 'code', 'list']}
variant="floating"
/>
```
### PKM Features
- **🔄 Real-time Collaboration**: Multi-user editing with presence indicators
- **🤖 AI Integration**: Smart suggestions, auto-tagging, and content enhancement
- **🔗 Bidirectional Linking**: Create and navigate knowledge connections
- **📊 Multiple Views**: Table, kanban, graph, timeline, and calendar views
- **🏷️ Semantic Tagging**: AI-powered concept extraction and organization
- **📱 Responsive Design**: Optimized for desktop and mobile PKM workflows
- **🔍 Advanced Search**: Full-text search with semantic understanding
- **📤 Export Capabilities**: Multiple format support (Markdown, JSON, CSV)
### Getting Started with PKM
```bash
npm install claritykit-svelte
```
```svelte
<script>
import {
BlockEditor,
KnowledgeGraph,
SemanticTagger,
MaterialViewTable
} from 'claritykit-svelte';
import 'claritykit-svelte/styles/tokens.css';
import 'claritykit-svelte/styles/components.css';
let notes = [];
let tags = [];
</script>
<!-- Your PKM Application -->
<main class="pkm-app">
<BlockEditor placeholder="Capture your thoughts..." />
<KnowledgeGraph nodes={notes} />
<MaterialViewTable data={notes} />
</main>
```
## 🔬 Research Components (NEW in v1.6.0)
ClarityKit now includes specialized components for academic research and paper management workflows.
### CitationFormatter
Format citations in multiple academic styles:
```svelte
<script>
import { CitationFormatter } from 'claritykit-svelte';
const paper = {
title: "Machine Learning Applications in Healthcare",
authors: ["Smith, J.", "Doe, A."],
year: 2024,
journal: "Journal of AI Research",
volume: 15,
pages: "123-145"
};
</script>
<CitationFormatter
{paper}
style="apa"
editable={true}
onEdit={(updatedPaper) => console.log('Updated:', updatedPaper)}
/>
```
### PaperMetadataCard
Display and edit research paper metadata:
```svelte
<script>
import { PaperMetadataCard } from 'claritykit-svelte';
const metadata = {
title: "Research Paper Title",
authors: ["Author One", "Author Two"],
abstract: "Paper abstract here...",
keywords: ["AI", "machine learning", "research"],
doi: "10.1000/182"
};
</script>
<PaperMetadataCard
{metadata}
editable={true}
showValidation={true}
onSave={(updated) => console.log('Saved:', updated)}
/>
```
### ResearchDiscoveryPanel
Discover and explore research papers:
```svelte
<script>
import { ResearchDiscoveryPanel } from 'claritykit-svelte';
let searchQuery = "";
let filters = { year: "2024", field: "computer-science" };
</script>
<ResearchDiscoveryPanel
bind:searchQuery
bind:filters
enableAIRecommendations={true}
onPaperSelect={(paper) => console.log('Selected:', paper)}
/>
```
### Research Features
- **📄 Citation Management**: Support for APA, MLA, Chicago, and IEEE citation styles
- **🔍 Paper Discovery**: AI-powered research paper recommendations
- **📊 Metadata Validation**: Ensure citation completeness and accuracy
- **🏷️ Keyword Extraction**: Automatic keyword and topic identification
- **📈 Progress Tracking**: Monitor research paper processing and analysis
- **🔗 DOI Integration**: Automatic metadata fetching from DOI lookups
## 🛡️ Quality Assurance
ClarityKit maintains the highest standards of quality through comprehensive automated testing and quality gates:
### Continuous Integration
- **Multi-Node Testing**: Automated testing across Node.js 18, 20, and 22
- **Accessibility Testing**: Automated WCAG 2.1 AA compliance verification
- **Cross-Browser Testing**: Chromium, Firefox, Safari, and Edge support
- **Visual Regression Testing**: Chromatic integration for visual consistency
- **Security Auditing**: Automated vulnerability scanning and dependency updates
### Quality Gates
- **Test Coverage**: Minimum 85% code coverage requirement
- **Type Safety**: Full TypeScript coverage with strict mode
- **Accessibility Compliance**: Automated axe-core testing
- **Component Testing**: Individual component and utility testing
- **Build Verification**: Package integrity and SSR compatibility checks
### Development Workflow
- **Automated Releases**: Semantic versioning with Changesets
- **Dependency Updates**: Automated security updates via Dependabot
- **Code Quality**: ESLint, Prettier, and Stylelint enforcement
- **Performance Monitoring**: Bundle size analysis and optimization
## 📖 Documentation
### Primary Resources
- **[Storybook Documentation](https://claritykit-svelte.netlify.app)** - Interactive component examples and API documentation
- **[Contributing Guide](./CONTRIBUTING.md)** - Comprehensive guide for contributors
- **[Accessibility Guidelines](./docs/accessibility-guidelines.md)** - WCAG compliance and accessibility patterns
- **[ADHD Design Principles](./docs/therapeutic-design-principles.md)** - Cognitive load optimization strategies
### Additional Documentation
- **[Component API Reference](./docs/component-api-reference.md)** - Complete API documentation
- **[SSR Integration Guide](./documentation/SSR-Integration-Guide.md)** - Server-side rendering setup
- **[Migration Guides](./documentation/)** - Version upgrade instructions
- **[Design System](./docs/design-system.md)** - Design tokens and styling guidelines
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for:
- Development setup and workflow
- Component development guidelines
- Testing requirements
- Accessibility standards
- ADHD optimization principles
- Pull request process
### Quick Contribution Setup
```bash
# Fork and clone the repository
git clone https://github.com/your-username/ClarityKit_svelte.git
cd ClarityKit_svelte
# Install dependencies
npm ci
# Start development environment
npm run storybook
# Run tests
npm test
```
## Development
### Setup
```bash
# Clone the repository
git clone https://github.com/warkrismagic/ClarityKit_svelte.git
cd ClarityKit_svelte
# Install dependencies
npm install
# Start Storybook
npm run storybook
```
### Scripts
- `npm run dev`: Start development server
- `npm run build`: Build the library
- `npm run storybook`: Start Storybook
- `npm run build-storybook`: Build Storybook
- `npm run test`: Run tests
- `npm run lint`: Run linting
## License
Apache License 2.0