🎨 hexaWebShare

A comprehensive Svelte 5 component library with 100+ production-ready UI components

Documentation • Getting Started • Contributing • Storybook

---

🌟 Features

• ✨ 100+ Components - Comprehensive UI components across 6 categories
• 🎨 DaisyUI + Tailwind - Beautiful, themeable components
• 🔥 Svelte 5 - Built with the latest Svelte features and runes
• 📘 TypeScript - Fully typed with excellent IDE support
• 📖 Storybook - Interactive component documentation
• ♿ Accessible - WCAG-compliant components
• 🎯 Production-Ready - Optimized and tested
• 🌓 Dark Mode - Full theme support out of the box

---

📦 Component Categories

Core Components

Essential UI building blocks for any application:

• Buttons, Forms, Layout, Typography
• Media, Data Display, Feedback
• Modals, Dropdowns, Navigation

Admin Components

Admin panel and dashboard components:

• Dashboards, KPI Cards, Charts
• CRUD Tables, Data Management
• User Roles & Permissions

B2B Components

Enterprise workspace features:

• Workspace & Team Management
• Projects, Clients, Invoices
• Kanban Boards, Workflows

E-commerce Components

Online store building blocks:

• Product Listings & Details
• Shopping Cart & Checkout
• Order Management

Marketing Components

Marketing and content sections:

• Hero Sections, Features
• Testimonials, Pricing
• Blog Layouts, CTAs

Utility Components

Cross-cutting utilities:

• Auth Layouts, Error Boundaries
• Search Bars, Filters

---

🚀 Quick Start

Prerequisites

• Node.js 18+ (Download)
• pnpm 9+ (Install: npm install -g pnpm)
• Git for version control

Requirements

• Svelte >= 5.0.0 (uses runes: $props, $derived, $effect, {@render})
• Client-side only - This library is designed for client-side rendering. SSR/hydration is not currently supported.

Why Svelte 5?

This library uses Svelte 5's new runes syntax throughout all components. Projects using Svelte 4 will encounter build errors.

SSR/Hydration Notice

Components generate unique IDs at runtime using crypto.randomUUID(). This approach works perfectly for client-side rendering but is not compatible with SSR hydration. If you need SSR support, please open an issue to discuss implementation strategies.

Installation for Development

1. Clone the repository

git clone https://github.com/hTuneSys/hexaWebShare.git
cd hexaWebShare

2. Install root dependencies and setup Husky

pnpm install

This will:

• Install Husky for Git hooks
• Setup pre-commit hooks for REUSE compliance
• Prepare the development environment

3. Navigate to the component library

cd hexawebshare

4. Install component library dependencies

pnpm install

5. Start Storybook

pnpm storybook

Storybook will open at http://localhost:6006

Alternative: SvelteKit Dev Server

cd hexawebshare
pnpm dev

Opens at http://localhost:5173

---

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Essential Guides

• Getting Started - Setup and installation
• Contributing - How to contribute
• Development Guide - Development workflow
• Architecture - System architecture

Git Workflow

• Branch Strategy - Branch naming and usage
• Commit Strategy - Commit message format
• PR Strategy - Pull request guidelines
• Labelling Strategy - Issue labels

Project Info

• Project Structure - Directory organization
• Configuration - Config files explained
• Style Guide - Code style conventions
• FAQ - Frequently asked questions

📖 Full Documentation Index

---

🛠️ Development Workflow

Available Commands

In the hexawebshare/ directory:

Command	Description
pnpm install	Install dependencies
pnpm dev	Start SvelteKit dev server
pnpm storybook	Start Storybook dev server
pnpm build	Build library package
pnpm build-storybook	Build static Storybook
pnpm check	TypeScript type checking
pnpm format	Format code with Prettier
pnpm lint	Check code formatting

Development Flow

# 1. Install root dependencies (Husky)
pnpm install

# 2. Navigate to component library
cd hexawebshare

# 3. Install component dependencies
pnpm install

# 4. Start Storybook
pnpm storybook

# 5. Make your changes
# (Storybook will hot-reload automatically)

# 6. Check types
pnpm check

# 7. Format code
pnpm format

# 8. Commit changes
git add .
git commit -m "feat(Component): add new feature"
# Git hooks will automatically run:
# 1. REUSE compliance check (pre-commit)
# 2. Commit message validation (commit-msg)

---

🔐 Git Hooks & Quality Checks

This project uses Git hooks to ensure code quality and compliance. Two hooks are automatically configured:

1. Pre-commit Hook - REUSE Compliance

Checks that all files have proper SPDX license headers.

Required tool: REUSE

# Option 1: Install with pipx (recommended)
pipx install reuse

# Option 2: Install with pip
pip install --user reuse

When it runs: Before each commit

git commit -m "feat: add new component"
# 🔍 Running REUSE compliance check...
# ✅ REUSE compliance check PASSED!

2. Commit-msg Hook - Commit Message Validation

Validates commit messages follow Conventional Commits format.

Required tools: Commitlint (installed in hexawebshare/node_modules)

When it runs: Before each commit (after pre-commit)

Required format:

<type>(<optional-scope>): <description>

Allowed types:

• feat - New feature
• fix - Bug fix
• docs - Documentation changes
• style - Code formatting (no logic change)
• refactor - Code restructuring
• perf - Performance improvement
• test - Test changes
• chore - Maintenance tasks
• ci - CI/CD changes
• build - Build system changes
• release - Release preparation
• hotfix - Critical emergency fix

Examples:

# ✅ Valid commits
git commit -m "feat(Button): add loading state prop"
git commit -m "fix(Modal): resolve focus trap issue"
git commit -m "docs(README): update installation steps"

# ❌ Invalid commits
git commit -m "update button"              # Missing type
git commit -m "added new feature"          # Wrong tense
git commit -m "feat: buton eklendi"        # Non-English

What happens during commit:

git commit -m "feat(Button): add loading state"
# 🔍 Running REUSE compliance check...
# ✅ REUSE compliance check PASSED!
# 🔍 Running Commitlint check...
# ✅ Commit message validation PASSED!

See docs/COMMIT_STRATEGY.md for detailed commit message guidelines.

---

🧪 Quality Checks

Before committing, ensure your code passes all checks:

cd hexawebshare

# Type checking
pnpm check

# Code formatting
pnpm format

# Linting
pnpm lint

# Build verification
pnpm build

# Storybook build
pnpm build-storybook

---

🎨 Using Components

In Your Svelte App

<script lang="ts">
  import { Button, Card, Modal } from 'hexawebshare';
  
  let showModal = $state(false);
</script>

<Card>
  <h2>Welcome to hexaWebShare</h2>
  <Button 
    label="Open Modal" 
    variant="primary"
    onclick={() => showModal = true}
  />
</Card>

{#if showModal}
  <Modal onclose={() => showModal = false}>
    <h3>Modal Content</h3>
    <p>This is a modal from hexaWebShare!</p>
  </Modal>
{/if}

Creating a New Component

<!-- src/components/core/buttons/MyButton.svelte -->
<script lang="ts">
  interface Props {
    label: string;
    variant?: 'primary' | 'secondary';
    onclick?: () => void;
  }
  
  const { 
    label, 
    variant = 'primary',
    onclick,
  }: Props = $props();
</script>

<button 
  class="btn {variant === 'primary' ? 'btn-primary' : 'btn-secondary'}"
  onclick={onclick}
>
  {label}
</button>

---

🏗️ Project Structure

hexaWebShare/
├── .github/              # GitHub configurations
│   ├── workflows/        # CI/CD workflows
│   └── ISSUE_TEMPLATE/   # Issue templates
├── .husky/               # Git hooks (pre-commit)
├── docs/                 # Comprehensive documentation
├── hexawebshare/         # Main component library
│   ├── .storybook/       # Storybook configuration
│   ├── src/
│   │   ├── components/   # Component library
│   │   │   ├── core/     # Core components
│   │   │   ├── admin/    # Admin components
│   │   │   ├── b2b/      # B2B components
│   │   │   ├── ecommerce/# E-commerce components
│   │   │   ├── marketing/# Marketing components
│   │   │   └── utility/  # Utility components
│   │   ├── lib/          # Library exports
│   │   └── routes/       # SvelteKit showcase
│   └── package.json      # Component library dependencies
├── LICENSES/             # License files
├── package.json          # Root package (Husky setup)
└── README.md             # This file

---

🤝 Contributing

We welcome contributions! Please read our Contributing Guide to get started.

Quick Contribution Checklist

• Read CONTRIBUTING.md
• Follow BRANCH_STRATEGY.md for branch naming
• Follow COMMIT_STRATEGY.md for commit messages
• Ensure all quality checks pass
• Add SPDX headers to new files
• Create Storybook stories for new components
• Update documentation if needed

Branch Naming

# Feature
git checkout -b feat/add-tooltip-component

# Bug fix
git checkout -b fix/modal-close-button

# Documentation
git checkout -b docs/update-readme

Commit Messages

# Format: <type>(<scope>): <description>
git commit -m "feat(Button): add loading state prop"
git commit -m "fix(Modal): resolve focus trap issue"
git commit -m "docs(README): update installation steps"

---

📋 Continuous Integration

Pull requests automatically run quality checks via GitHub Actions:

• ✅ TypeScript type checking
• ✅ Code formatting validation
• ✅ Build verification
• ✅ Storybook build test

See .github/workflows/ci.yml for details.

---

📄 License

This project is licensed under the MIT License.

SPDX-FileCopyrightText: 2025 hexaTune LLC
SPDX-License-Identifier: MIT

---

🙏 Acknowledgments

Built with amazing open-source technologies:

• Svelte - The web framework
• DaisyUI - Component library
• Tailwind CSS - Utility CSS framework
• Storybook - Component development
• TypeScript - Type safety
• Vite - Build tool

---

📞 Contact & Support

• Website: hexatune.com
• GitHub: hTuneSys/hexaWebShare
• Issues: Report a bug
• Discussions: Ask questions
• Email: info@hexatune.com

---

Built with ❤️ by hexaTune LLC

⭐ Star us on GitHub if you find this project useful!