14 KiB
Adding New Tools & Components
This guide covers creating new networking tools and components for the app. The process involves creating a Svelte component, adding it to the navigation, and integrating it with the app's systems.
Tool Structure Overview
Tools in the app follow a consistent structure:
- Utility Functions (
src/lib/utils/) - Core calculation logic - Tool Component (
src/lib/components/tools/) - UI and interaction - Page Component (
src/routes/section/tool-name/+page.svelte) - Route wrapper - Navigation Entry (
src/lib/constants/nav.ts) - Menu integration - Tests (
tests/unit/andtests/e2e/) - Quality assurance
Step-by-Step Guide
1. Create Utility Functions
Start by implementing the core business logic in src/lib/utils/:
// src/lib/utils/my-network-tool.ts
export interface MyToolResult {
input: string;
output: string;
details: string[];
}
export function calculateMyTool(input: string): MyToolResult {
// Input validation
if (!input || input.trim() === '') {
throw new Error('Input is required');
}
// Core calculation logic
const result = performCalculation(input);
return {
input: input.trim(),
output: result,
details: getCalculationDetails(result)
};
}
function performCalculation(input: string): string {
// Your calculation logic here
return processedInput;
}
2. Create Tool Component
Implement the UI component in src/lib/components/tools/:
<!-- src/lib/components/tools/MyNetworkTool.svelte -->
<script lang="ts">
import { calculateMyTool, type MyToolResult } from '$lib/utils/my-network-tool.js';
import { validateInput } from '$lib/utils/validation.js';
import Tooltip from '$lib/components/global/Tooltip.svelte';
import SvgIcon from '$lib/components/global/SvgIcon.svelte';
import { tooltip } from '$lib/actions/tooltip.js';
// Reactive state using Svelte 5 $state
let input = $state('example-input');
let result: MyToolResult | null = $state(null);
let error = $state('');
let isCalculating = $state(false);
let hasEverShownResults = $state(false);
// Reactive calculation using $effect
$effect(() => {
if (input && validateInput(input)) {
isCalculating = true;
try {
result = calculateMyTool(input);
error = '';
if (!hasEverShownResults) {
hasEverShownResults = true;
}
} catch (err) {
error = err instanceof Error ? err.message : 'Calculation failed';
result = null;
} finally {
isCalculating = false;
}
} else {
result = null;
error = '';
}
});
// Clipboard functionality
let copiedStates = $state<Record<string, boolean>>({});
async function copyToClipboard(text: string, id: string) {
try {
await navigator.clipboard.writeText(text);
copiedStates[id] = true;
setTimeout(() => { copiedStates[id] = false; }, 2000);
} catch (err) {
console.error('Failed to copy:', err);
}
}
</script>
<div class="tool-container">
<section class="input-section">
<h2>My Network Tool</h2>
<p>Description of what this tool does and how to use it.</p>
<div class="input-group">
<label for="tool-input">Input:</label>
<input
id="tool-input"
type="text"
bind:value={input}
placeholder="Enter your input here"
class="input-field"
use:tooltip={{ content: "Helpful tooltip text" }}
/>
</div>
{#if error}
<div class="error-message">
<SvgIcon name="alert-circle" />
{error}
</div>
{/if}
</section>
{#if result}
<section class="results-section">
<h3>Results</h3>
<div class="result-item">
<span class="label">Output:</span>
<span class="value">{result.output}</span>
<button
class="copy-btn"
onclick={() => copyToClipboard(result.output, 'output')}
>
<SvgIcon name={copiedStates.output ? 'check' : 'copy'} />
</button>
</div>
{#if result.details.length > 0}
<div class="details">
<h4>Details:</h4>
<ul>
{#each result.details as detail}
<li>{detail}</li>
{/each}
</ul>
</div>
{/if}
</section>
{/if}
</div>
<style lang="scss">
.tool-container {
max-width: 800px;
margin: 0 auto;
padding: var(--spacing-lg);
}
.input-section {
margin-bottom: var(--spacing-lg);
h2 {
color: var(--text-primary);
margin-bottom: var(--spacing-sm);
}
p {
color: var(--text-secondary);
margin-bottom: var(--spacing-lg);
}
}
.input-group {
display: flex;
flex-direction: column;
gap: var(--spacing-sm);
label {
font-weight: 500;
color: var(--text-primary);
}
}
.input-field {
padding: var(--spacing-sm);
border: 1px solid var(--border-primary);
border-radius: var(--radius-md);
background: var(--bg-secondary);
color: var(--text-primary);
font-family: var(--font-mono);
&:focus {
outline: none;
border-color: var(--color-primary);
}
}
.error-message {
display: flex;
align-items: center;
gap: var(--spacing-sm);
color: var(--color-error);
margin-top: var(--spacing-sm);
padding: var(--spacing-sm);
background: color-mix(in srgb, var(--color-error), transparent 90%);
border-radius: var(--radius-md);
}
.results-section {
background: var(--bg-secondary);
border-radius: var(--radius-md);
padding: var(--spacing-lg);
border: 1px solid var(--border-primary);
}
.result-item {
display: flex;
align-items: center;
gap: var(--spacing-sm);
margin-bottom: var(--spacing-md);
.label {
font-weight: 500;
color: var(--text-secondary);
min-width: 80px;
}
.value {
font-family: var(--font-mono);
color: var(--text-primary);
flex: 1;
}
}
.copy-btn {
background: none;
border: 1px solid var(--border-primary);
border-radius: var(--radius-sm);
padding: var(--spacing-xs);
color: var(--text-secondary);
cursor: pointer;
display: flex;
align-items: center;
justify-content: center;
&:hover {
background: var(--surface-hover);
color: var(--color-primary);
}
}
.details {
ul {
list-style: none;
padding: 0;
li {
padding: var(--spacing-xs) 0;
color: var(--text-secondary);
font-family: var(--font-mono);
font-size: var(--font-size-sm);
}
}
}
</style>
3. Create Page Route
Create the route file that wraps your component:
<!-- src/routes/networking/my-tool/+page.svelte -->
<script lang="ts">
import MyNetworkTool from '$lib/components/tools/MyNetworkTool.svelte';
import '../../../styles/pages.scss';
</script>
<MyNetworkTool />
4. Add to Navigation
Update the navigation configuration in src/lib/constants/nav.ts:
// Add to the appropriate section in SUB_NAV
{
href: '/networking/my-tool',
label: 'My Network Tool',
description: 'Brief description of what the tool does',
keywords: ['keyword1', 'keyword2', 'calculation', 'networking'],
icon: 'calculator' // Choose from icon-map.ts
}
5. Add Icon (if needed)
If you need a custom icon, add it to src/lib/constants/icon-map.ts:
export const iconMap: Record<string, string> = {
// ... existing icons
'my-tool-icon': `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 640">
<!-- Your SVG path here -->
</svg>`,
};
6. Write Tests
Create unit tests for your utility functions:
// tests/unit/utils/my-network-tool.test.ts
import { describe, test, expect } from 'vitest';
import { calculateMyTool } from '$lib/utils/my-network-tool';
describe('My Network Tool', () => {
test('should calculate correctly with valid input', () => {
const result = calculateMyTool('valid-input');
expect(result.input).toBe('valid-input');
expect(result.output).toBeDefined();
expect(result.details).toBeInstanceOf(Array);
});
test('should throw error with invalid input', () => {
expect(() => calculateMyTool('')).toThrow('Input is required');
expect(() => calculateMyTool('invalid')).toThrow();
});
test('should handle edge cases', () => {
// Test boundary conditions
const result = calculateMyTool('edge-case-input');
expect(result.output).toBe('expected-output');
});
});
Add E2E tests for the complete user flow:
// tests/e2e/tools/my-network-tool.spec.ts
import { test, expect } from '@playwright/test';
test.describe('My Network Tool', () => {
test('should calculate results when valid input provided', async ({ page }) => {
await page.goto('/networking/my-tool');
// Fill input
await page.fill('input[id="tool-input"]', 'test-input');
// Verify results appear
await expect(page.locator('.results-section')).toBeVisible();
await expect(page.locator('.result-item .value')).toContainText('expected-output');
});
test('should show error for invalid input', async ({ page }) => {
await page.goto('/networking/my-tool');
await page.fill('input[id="tool-input"]', 'invalid-input');
await expect(page.locator('.error-message')).toBeVisible();
});
test('should copy results to clipboard', async ({ page }) => {
await page.goto('/networking/my-tool');
await page.fill('input[id="tool-input"]', 'valid-input');
await page.click('.copy-btn');
// Verify copy success (check icon change)
await expect(page.locator('.copy-btn svg')).toContainText('check');
});
});
Component Patterns & Best Practices
State Management
Use Svelte 5's $state for reactive state:
// Good: Reactive state
let input = $state('');
let result = $state(null);
let loading = $state(false);
// Good: Reactive calculations
$effect(() => {
if (input) {
loading = true;
try {
result = calculateSomething(input);
} finally {
loading = false;
}
}
});
Input Validation
Implement consistent input validation:
// Good: Comprehensive validation
function validateInput(input: string): ValidationResult {
if (!input || input.trim() === '') {
return { valid: false, error: 'Input is required' };
}
if (input.length > 1000) {
return { valid: false, error: 'Input too long' };
}
if (!inputPattern.test(input)) {
return { valid: false, error: 'Invalid format' };
}
return { valid: true };
}
Error Handling
Provide meaningful error messages:
// Good: Specific error messages
try {
const result = complexCalculation(input);
return result;
} catch (error) {
if (error instanceof ValidationError) {
throw new Error(`Invalid input: ${error.message}`);
} else if (error instanceof CalculationError) {
throw new Error(`Calculation failed: ${error.details}`);
} else {
throw new Error('An unexpected error occurred');
}
}
Accessibility
Ensure your tools are accessible:
<!-- Good: Accessible form -->
<div class="input-group">
<label for="cidr-input">CIDR Network:</label>
<input
id="cidr-input"
type="text"
bind:value={input}
aria-describedby="cidr-help"
aria-invalid={!!error}
/>
<div id="cidr-help" class="help-text">
Enter a CIDR notation like 192.168.1.0/24
</div>
{#if error}
<div class="error" role="alert" aria-live="polite">
{error}
</div>
{/if}
</div>
Performance
Optimize for large calculations:
// Good: Debounced calculations
let debounceTimer: number;
$effect(() => {
clearTimeout(debounceTimer);
if (input) {
debounceTimer = setTimeout(() => {
performExpensiveCalculation(input);
}, 300);
}
});
Integration Checklist
Before submitting your new tool:
- Utility functions tested with 85%+ coverage
- Component follows Svelte 5 patterns
- Navigation entry added with appropriate keywords
- Icon available (existing or custom)
- E2E tests cover main user flows
- Error handling provides helpful messages
- Accessibility features implemented
- Documentation includes usage examples
- Performance optimized for typical inputs
Common Patterns
IP Address Tools
// Pattern for IP-related tools
export function validateIPAddress(ip: string): boolean {
const ipv4Pattern = /^(\d{1,3}\.){3}\d{1,3}$/;
const ipv6Pattern = /^([0-9a-fA-F]{0,4}:){2,7}[0-9a-fA-F]{0,4}$/;
return ipv4Pattern.test(ip) || ipv6Pattern.test(ip);
}
CIDR Tools
// Pattern for CIDR-related tools
export function parseCIDR(cidr: string): { ip: string; prefix: number } {
const [ip, prefixStr] = cidr.split('/');
const prefix = parseInt(prefixStr, 10);
if (!validateIPAddress(ip) || prefix < 0 || prefix > 32) {
throw new Error('Invalid CIDR notation');
}
return { ip, prefix };
}
DNS Tools
// Pattern for DNS-related tools
export function validateDomain(domain: string): boolean {
const domainPattern = /^[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
return domainPattern.test(domain) && domain.length <= 253;
}
Your new tool will automatically integrate with:
- Global search - Keywords make it discoverable
- Bookmarks system - Users can save favourite tools
- Accessibility - CSS variables and ARIA support
- Offline mode - Service worker caching
- Theme system - CSS variables adapt to all themes
IPv6 addresses can contain up to 39 characters in their compressed form. Consider this when designing input validation for IPv6-related tools.