Greater Components

Modern UI components for building accessible Fediverse applications

Documentation • Playground • Getting Started • Examples • Contributing

---

✨ What is Greater Components?

Greater Components is a comprehensive, production-ready UI component library designed specifically for building modern Fediverse applications. Built with Svelte 5, TypeScript, and accessibility-first principles, it provides everything you need to create engaging social media experiences that work for everyone.

Architected for Lesser: Greater Components is purpose-built for the Lesser ActivityPub server, with full support for advanced features like quote posts, community notes, AI-powered moderation, trust graphs, cost analytics, and real-time federation health monitoring. While compatible with other ActivityPub servers (Mastodon, Pleroma, etc.), Lesser integration unlocks the complete feature set.

🎯 Perfect for

• Lesser-powered applications with advanced moderation and analytics
• Mastodon clients and alternative interfaces
• ActivityPub applications and services
• Fediverse tools and analytics platforms
• Social media dashboards and moderation tools
• Any modern web application needing high-quality UI components

🚀 Quick Start

Installation

The Greater CLI copies components as source code to your project (shadcn-style), giving you full control:

# Install the CLI from GitHub Releases (recommended)
# Replace `greater-vX.Y.Z` with a real tag from https://github.com/equaltoai/greater-components/releases
npm install -g https://github.com/equaltoai/greater-components/releases/download/greater-vX.Y.Z/greater-components-cli.tgz

# Initialize in your project
cd my-sveltekit-app
greater init

# Add components
greater add button modal menu

# Add a complete face (component bundle)
greater add faces/social

# Update installed components to a specific Git tag
greater update --ref greater-vX.Y.Z

Benefits: Full source ownership, easy customization, deterministic installs via Git tags, no npm publish tokens required.

📖 See CLI Guide for complete documentation.

Basic Usage

Styled Components (Quick Start)

<script>
	import { Button, Modal, ThemeProvider } from '@equaltoai/greater-components/primitives';
	import { HomeIcon, SettingsIcon } from '@equaltoai/greater-components/icons';

	let showModal = false;
</script>

<ThemeProvider>
	<main>
		<Button variant="solid" onclick={() => (showModal = true)}>
			{#snippet prefix()}<SettingsIcon />{/snippet}
			Open Settings
		</Button>

		<Modal bind:open={showModal} title="Settings" size="md">
			<p>Your settings panel content goes here.</p>

			{#snippet footer()}
				<Button variant="ghost" onclick={() => (showModal = false)}>Cancel</Button>
				<Button variant="solid">Save Changes</Button>
			{/snippet}
		</Modal>
	</main>
</ThemeProvider>

Headless Components (Maximum Control) 🆕

<script>
	import { createButton } from '@equaltoai/greater-components/headless/button';
	import { SettingsIcon } from '@equaltoai/greater-components/icons';

	const button = createButton({
		onClick: () => console.log('Clicked!'),
		loading: false,
	});
</script>

<!-- Style however you want -->
<button use:button.actions.button class="your-custom-styles">
	<SettingsIcon />
	{#if button.state.loading}
		Loading...
	{:else}
		Open Settings
	{/if}
</button>

<style>
	.your-custom-styles {
		/* Complete styling freedom */
		padding: 1rem 2rem;
		background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
		color: white;
		border: none;
		border-radius: 0.5rem;
		font-weight: 600;
		cursor: pointer;
	}
</style>

Fediverse Example (Lesser-native)

<script>
	import { LesserGraphQLAdapter } from '@equaltoai/greater-components/adapters';
	import { TimelineVirtualizedReactive } from '@equaltoai/greater-components/faces/social';

	// Initialize Lesser adapter with GraphQL endpoint
	const adapter = new LesserGraphQLAdapter({
		httpEndpoint: 'https://your-instance.social/graphql',
		token: 'your-auth-token',
	});

	const view = {
		type: 'home',
	};
</script>

<TimelineVirtualizedReactive {adapter} {view} estimateSize={320} />

✅ Phase 5 – Documentation & Testing

• Demo suite docs: /demo-suite plus /demo-suite/{timeline,profile,settings,search} now outline props, handlers, accessibility, and performance notes for every Phase 4 surface.
• New primitives coverage: /components/tabs and /components/switch pages document the runes-based API with live demos.
• Testing upgrades: Vitest coverage for adapters/stores plus Playwright flows in packages/testing/tests/demo/*.spec.ts.

📦 Package Overview

All packages are installed as source code via the CLI. No npm registry dependency required.

Core Packages

Package	Description
headless	🆕 Headless UI primitives - behavior without styling
primitives	Essential UI components (Button, Modal, TextField, etc.)
tokens	Design system tokens and theming
icons	300+ SVG icons including Fediverse-specific ones

Specialized Packages

Package	Description
faces/social	Social media components (Timeline, Profile, etc.)
faces/artist	Artist portfolio and gallery components
faces/blog	Blog and content publishing components
faces/community	Community and forum components
utils	Utility functions for web applications
adapters	Protocol adapters for Fediverse servers
testing	Testing utilities and accessibility helpers

🌟 Key Features

🎨 Modern Design System

• Design Tokens: Systematic approach to colors, typography, spacing
• Multiple Themes: Light, dark, and high-contrast modes included
• CSS Custom Properties: Easy theming without rebuilds
• Responsive: Mobile-first design with tablet and desktop breakpoints

♿ Accessibility First

• WCAG 2.1 AA Compliant: Meets international accessibility standards
• Keyboard Navigation: Full keyboard support for all interactive elements
• Screen Reader Optimized: Proper ARIA labels and semantic markup
• Focus Management: Smart focus handling for modals and menus
• Reduced Motion: Respects user motion preferences

⚡ Performance Optimized

• Zero Runtime: Svelte 5 compiles to minimal JavaScript
• Tree Shakeable: Import only the components you use
• Virtual Scrolling: Handle thousands of items efficiently
• Bundle Analysis: Optimized for minimal application impact

🔧 Developer Experience

• TypeScript First: Complete type safety throughout
• Comprehensive Docs: JSDoc comments on all public APIs
• Component Playground: Interactive SvelteKit sandbox for rapid prototyping
• Hot Reload: Fast development with Vite
• Automated Testing: 100% test coverage

🌐 Lesser-First Architecture

• ActivityPub Types: Complete TypeScript definitions aligned with Lesser schema
• GraphQL Integration: Fully typed queries, mutations, and subscriptions via codegen
• Real-time Streaming: 21 subscription types (quotes, trust updates, cost alerts, moderation events, etc.)
• Advanced Features: Quote posts, community notes, AI analysis, trust graphs, cost dashboards
• Multi-server Support: Works with Lesser (primary), Mastodon, Pleroma, and other ActivityPub servers
• Protocol Adapters: Abstract away server differences with unified models

🚀 Lesser-Exclusive Features

• Quote Posts: Full quote creation, display, and permission controls
• Community Notes: Collaborative fact-checking with voting and moderation
• AI Insights: Automated content analysis (toxicity, sentiment, spam, NSFW detection)
• Trust Graph: Reputation scores, vouches, and relationship visualization
• Cost Analytics: Real-time cost tracking, budgets, and federation optimization
• Thread Synchronization: Fetch missing replies and resolve incomplete threads
• Severed Relationships: Monitor and recover from federation breaks
• Hashtag Controls: Follow hashtags with notification preferences and muting
• Advanced Moderation: AI-powered moderation queue with pattern matching

🎨 Theming & Customization

Greater Components includes a powerful theming system based on design tokens:

/* Override design tokens */
:root {
	--gr-color-primary-600: #your-brand-color;
	--gr-typography-fontFamily-sans: 'Your Font', system-ui;
	--gr-radii-lg: 12px;
}

/* Component customization */
.gr-button--solid {
	background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

Built-in Themes:

• 🌞 Light Theme - Clean, modern light interface
• 🌙 Dark Theme - Easy-on-the-eyes dark mode
• ⚡ High Contrast - WCAG AAA compliant high contrast

🛠️ Requirements

• Node.js: >= 20.0.0
• TypeScript: >= 5.0.0 (optional but recommended)
• Svelte: >= 5.0.0
• Browser Support: Modern evergreen browsers

🧪 Testing

Greater Components includes comprehensive testing utilities:

import { render, fireEvent } from '@equaltoai/greater-components/testing';
import { Button } from '@equaltoai/greater-components/primitives';

test('button handles clicks', () => {
	const handleClick = vi.fn();
	const { getByRole } = render(Button, {
		props: { onclick: handleClick },
	});

	fireEvent.click(getByRole('button'));
	expect(handleClick).toHaveBeenCalled();
});

📚 Documentation & Resources

📖 Documentation

• Lesser Integration Guide - Complete Lesser setup and feature guide
• API Reference - Complete API documentation
• Component Documentation - Individual component guides
• Migration Guide - Upgrade instructions
• Troubleshooting - Common issues and solutions

🎮 Interactive Examples

• Playground - Live component playground
• Examples Repository - Real-world usage examples
• CodeSandbox Templates - Ready-to-fork templates

🤝 Community

• GitHub Discussions - Questions and community support
• Issue Tracker - Bug reports and feature requests
• Contributing Guide - How to contribute to the project

🔐 Security

Security is a top priority:

• Git tag based distribution - Releases are pinned to signed Git tags for supply chain security
• Checksum verification - All installed files are verified against checksums in registry/index.json
• Regularly audited for vulnerabilities
• AGPL-3.0 licensed for transparency

For security issues, email security@equalto.ai instead of using the public issue tracker.

🤝 Contributing

We welcome contributions! Whether you're:

• 🐛 Reporting bugs or suggesting features
• 📝 Improving documentation or examples
• 🔧 Contributing code or tests
• 🌍 Translating or internationalizing
• 🎨 Designing components or interfaces

Check out our Contributing Guide to get started.

Development Setup

# Clone the repository
git clone https://github.com/equaltoai/greater-components.git
cd greater-components

# Install dependencies
pnpm install

# Start development mode
pnpm dev

# Run tests
pnpm test

# Build all packages
pnpm build

📄 License

Greater Components is licensed under the AGPL-3.0-only License - see the LICENSE file for details.

This ensures that improvements to the library benefit the entire community and Fediverse ecosystem.

🙏 Acknowledgments

Built With

• 🔥 Svelte 5 - The magical disappearing framework
• 📘 TypeScript - JavaScript with types
• ⚡ Vite - Next generation frontend tooling
• 🧪 Vitest - Blazing fast unit testing
• 📚 Component playgrounds - Use the built-in SvelteKit demos under apps/playground
• 🎭 Playwright - Reliable end-to-end testing

Community

Special thanks to:

• The Svelte team for creating an amazing framework and the revolutionary runes system
• The Fediverse community for inspiration, feedback, and testing
• All contributors who have helped shape this library
• The accessibility community for guidance on inclusive design

---

Ready to build something great?

Get Started • View Components • Join Discussion

Made with ❤️ for the Fediverse community