@classic-homes/theme-svelte 0.1.0

package/dist/lib/types/layout.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Layout Types for Classic Theme
+ *
+ * These types define the interfaces for layout components including
+ * navigation, user data, and layout props.
+ */
+import type { Snippet } from 'svelte';
+/**
+ * Navigation item for sidebar and header navigation
+ */
+export interface NavItem {
+    /** Unique identifier for the item */
+    id: string;
+    /** Display name */
+    name: string;
+    /** URL to navigate to */
+    href: string;
+    /** Icon name (app renders via snippet) */
+    icon?: string;
+    /** Optional badge (notification count, etc.) */
+    badge?: string | number;
+    /** Role-based visibility */
+    roles?: string[];
+    /** Opens in new tab */
+    external?: boolean;
+    /** Whether this item is currently active */
+    active?: boolean;
+}
+/**
+ * Navigation section for grouping nav items
+ */
+export interface NavSection {
+    /** Unique identifier for the section */
+    id: string;
+    /** Optional section header */
+    title?: string;
+    /** Items in this section */
+    items: NavItem[];
+    /** Can section be collapsed */
+    collapsible?: boolean;
+    /** Is section currently expanded (for collapsible sections) */
+    expanded?: boolean;
+}
+/**
+ * User data for layout components
+ */
+export interface User {
+    /** Unique identifier */
+    id: string;
+    /** Display name */
+    name: string;
+    /** Email address */
+    email?: string;
+    /** Avatar URL */
+    avatar?: string;
+    /** User roles for authorization */
+    roles?: string[];
+    /** User initials (fallback for avatar) */
+    initials?: string;
+}
+/**
+ * Back link configuration for dashboard navigation
+ */
+export interface BackLink {
+    /** Link label (e.g., "Back to Dashboard") */
+    label: string;
+    /** Link URL */
+    href: string;
+    /** Icon name for the icon snippet */
+    icon?: string;
+}
+/**
+ * Quick link item for sidebar quick links section
+ */
+export interface QuickLink {
+    /** Unique identifier */
+    id: string;
+    /** Display label */
+    label: string;
+    /** URL to navigate to */
+    href: string;
+    /** Icon name (app renders via snippet) */
+    icon?: string;
+    /** Opens in new tab */
+    external?: boolean;
+    /** Accessible label for screen readers (used in icon-only mode) */
+    ariaLabel?: string;
+}
+/**
+ * Props for QuickLinks component
+ */
+export interface QuickLinksProps {
+    /** Array of quick link items */
+    links: QuickLink[];
+    /** Display mode: 'list' for stacked with labels, 'icons' for horizontal icons only */
+    display?: 'list' | 'icons';
+    /** Visual variant - light (default) or dark */
+    variant?: 'light' | 'dark';
+    /** Custom icon renderer */
+    icon?: Snippet<[QuickLink]>;
+    /** Additional classes */
+    class?: string;
+}
+/**
+ * Props for DashboardLayout component
+ */
+export interface DashboardLayoutProps {
+    /** Navigation sections for sidebar */
+    navigation: NavSection[];
+    /** Current user data */
+    user?: User;
+    /** Application name */
+    appName?: string;
+    /** Page title displayed in header */
+    pageTitle?: string;
+    /** Back link shown at top of sidebar navigation */
+    backLink?: BackLink;
+    /** Sidebar visual variant */
+    sidebarVariant?: 'light' | 'dark';
+    /** Whether sidebar is collapsed by default */
+    sidebarCollapsed?: boolean;
+    /** Whether to show the header */
+    showHeader?: boolean;
+    /** Custom logo snippet */
+    logo?: Snippet;
+    /** Custom icon renderer for nav items */
+    icon?: Snippet<[NavItem]>;
+    /** Quick links displayed at bottom of sidebar */
+    quickLinks?: QuickLink[];
+    /** Quick links display mode */
+    quickLinksDisplay?: 'list' | 'icons';
+    /** Custom icon renderer for quick links */
+    quickLinkIcon?: Snippet<[QuickLink]>;
+    /** Custom content at start of header */
+    headerStart?: Snippet;
+    /** Custom content at end of header */
+    headerEnd?: Snippet;
+    /** Custom user menu snippet */
+    userMenu?: Snippet<[User]>;
+    /** Sidebar footer content */
+    sidebarFooter?: Snippet;
+    /** Main content */
+    children: Snippet;
+}
+/**
+ * Props for PublicLayout component
+ */
+export interface PublicLayoutProps {
+    /** Navigation items for header */
+    navigation?: NavItem[];
+    /** Whether to show footer */
+    showFooter?: boolean;
+    /** Footer link sections */
+    footerLinks?: NavSection[];
+    /** Footer copyright text */
+    copyright?: string;
+    /** Custom logo snippet */
+    logo?: Snippet;
+    /** Custom header end content */
+    headerEnd?: Snippet;
+    /** Main content */
+    children: Snippet;
+}
+/**
+ * Props for Sidebar component
+ */
+export interface SidebarProps {
+    /** Navigation sections */
+    navigation: NavSection[];
+    /** Visual variant - light (default) or dark */
+    variant?: 'light' | 'dark';
+    /** Whether sidebar is collapsed */
+    collapsed?: boolean;
+    /** Whether currently on mobile */
+    isMobile?: boolean;
+    /** Whether mobile sidebar is open */
+    mobileOpen?: boolean;
+    /** Callback when mobile sidebar should close */
+    onClose?: () => void;
+    /** Custom logo snippet */
+    logo?: Snippet;
+    /** Custom icon renderer for nav items */
+    icon?: Snippet<[NavItem]>;
+    /** Quick links displayed at bottom of sidebar */
+    quickLinks?: QuickLink[];
+    /** Quick links display mode */
+    quickLinksDisplay?: 'list' | 'icons';
+    /** Custom icon renderer for quick links */
+    quickLinkIcon?: Snippet<[QuickLink]>;
+    /** Custom footer content */
+    footer?: Snippet;
+    /** Use stronger/thicker border */
+    strongBorder?: boolean;
+    /** Additional classes */
+    class?: string;
+}
+/**
+ * Props for Header component
+ */
+export interface HeaderProps {
+    /** Whether to show hamburger menu button (mobile) */
+    showMenuButton?: boolean;
+    /** Callback when menu button is clicked */
+    onMenuClick?: () => void;
+    /** Custom start content (left side) */
+    start?: Snippet;
+    /** Custom end content (right side) */
+    end?: Snippet;
+    /** Additional classes */
+    class?: string;
+}
+/**
+ * Props for Footer component
+ */
+export interface FooterProps {
+    /** Link sections */
+    links?: NavSection[];
+    /** Copyright text */
+    copyright?: string;
+    /** Show logo in footer */
+    showLogo?: boolean;
+    /** Custom content */
+    children?: Snippet;
+    /** Additional classes */
+    class?: string;
+}
+/**
+ * Props for AppShell component
+ */
+export interface AppShellProps {
+    /** Skip link target ID */
+    skipToId?: string;
+    /** Skip link text */
+    skipToText?: string;
+    /** Main content */
+    children: Snippet;
+}
+/**
+ * Props for FormPageLayout component
+ */
+export interface FormPageLayoutProps {
+    /** Page title (h1) */
+    title: string;
+    /** Page description text */
+    description: string;
+    /** Footer help text (supports HTML) */
+    helpText?: string;
+    /** Show the notices section (renders notices snippet if provided) */
+    showNotices?: boolean;
+    /** Main form content */
+    children: Snippet;
+    /** Optional notices content (alert cards, etc.) */
+    notices?: Snippet;
+    /** Optional sidebar content */
+    sidebar?: Snippet;
+    /** Additional classes for the container */
+    class?: string;
+}

package/dist/lib/types/layout.js

@@ -0,0 +1,7 @@
+/**
+ * Layout Types for Classic Theme
+ *
+ * These types define the interfaces for layout components including
+ * navigation, user data, and layout props.
+ */
+export {};

package/dist/lib/utils.d.ts

@@ -0,0 +1,6 @@
+import { type ClassValue } from 'clsx';
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Uses clsx for conditional classes and tailwind-merge to handle conflicts
+ */
+export declare function cn(...inputs: ClassValue[]): string;

package/dist/lib/utils.js

@@ -0,0 +1,9 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Uses clsx for conditional classes and tailwind-merge to handle conflicts
+ */
+export function cn(...inputs) {
+    return twMerge(clsx(inputs));
+}

package/dist/lib/validation.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Runtime validation utilities for Classic Theme components
+ *
+ * These utilities provide development-time warnings for common prop mistakes.
+ * They are designed to be tree-shaken in production builds.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    message?: string;
+}
+/**
+ * Validate that a required array prop is non-empty
+ *
+ * @param value - The array to validate
+ * @param propName - Name of the prop for error messages
+ * @param componentName - Name of the component for error messages
+ * @returns Validation result with valid status and optional message
+ *
+ * @example
+ * ```ts
+ * $effect(() => {
+ *   validateNonEmptyArray(options, 'options', 'Select');
+ * });
+ * ```
+ */
+export declare function validateNonEmptyArray<T>(value: T[] | undefined, propName: string, componentName: string): ValidationResult;
+/**
+ * Validate that a required prop is defined
+ *
+ * @param value - The value to validate
+ * @param propName - Name of the prop for error messages
+ * @param componentName - Name of the component for error messages
+ * @returns Validation result with valid status and optional message
+ *
+ * @example
+ * ```ts
+ * validateRequired(id, 'id', 'FormField');
+ * ```
+ */
+export declare function validateRequired<T>(value: T | undefined | null, propName: string, componentName: string): ValidationResult;
+/**
+ * Validate prop is one of allowed values
+ *
+ * @param value - The value to validate
+ * @param allowedValues - Array of allowed values
+ * @param propName - Name of the prop for error messages
+ * @param componentName - Name of the component for error messages
+ * @returns Validation result with valid status and optional message
+ *
+ * @example
+ * ```ts
+ * validateOneOf(variant, ['default', 'destructive', 'outline'], 'variant', 'Button');
+ * ```
+ */
+export declare function validateOneOf<T>(value: T, allowedValues: readonly T[], propName: string, componentName: string): ValidationResult;
+/**
+ * Validate a number is within a range
+ *
+ * @param value - The number to validate
+ * @param min - Minimum allowed value (inclusive)
+ * @param max - Maximum allowed value (inclusive)
+ * @param propName - Name of the prop for error messages
+ * @param componentName - Name of the component for error messages
+ * @returns Validation result with valid status and optional message
+ */
+export declare function validateRange(value: number, min: number, max: number, propName: string, componentName: string): ValidationResult;
+/**
+ * Batch validate multiple conditions
+ *
+ * @param validations - Array of validation results
+ * @returns true if all validations pass, false otherwise
+ *
+ * @example
+ * ```ts
+ * const isValid = validateProps([
+ *   validateRequired(id, 'id', 'Component'),
+ *   validateNonEmptyArray(items, 'items', 'Component'),
+ * ]);
+ * ```
+ */
+export declare function validateProps(validations: ValidationResult[]): boolean;
+/**
+ * Create a validator function for a specific component
+ * Useful for creating reusable validation in component files
+ *
+ * @param componentName - Name of the component
+ * @returns Object with bound validation functions
+ *
+ * @example
+ * ```ts
+ * const validate = createValidator('Select');
+ * validate.nonEmptyArray(options, 'options');
+ * validate.required(value, 'value');
+ * ```
+ */
+export declare function createValidator(componentName: string): {
+    nonEmptyArray: <T>(value: T[] | undefined, propName: string) => ValidationResult;
+    required: <T>(value: T | undefined | null, propName: string) => ValidationResult;
+    oneOf: <T>(value: T, allowedValues: readonly T[], propName: string) => ValidationResult;
+    range: (value: number, min: number, max: number, propName: string) => ValidationResult;
+};

package/dist/lib/validation.js

@@ -0,0 +1,170 @@
+/**
+ * Runtime validation utilities for Classic Theme components
+ *
+ * These utilities provide development-time warnings for common prop mistakes.
+ * They are designed to be tree-shaken in production builds.
+ */
+// Detect development mode in a way that works across different environments
+const getIsDev = () => {
+    try {
+        // Vite/SvelteKit environment
+        // @ts-expect-error - import.meta.env may not exist in all environments
+        if (typeof import.meta !== 'undefined' && import.meta.env?.DEV !== undefined) {
+            // @ts-expect-error - accessing env.DEV
+            return import.meta.env.DEV === true;
+        }
+    }
+    catch {
+        // Ignore errors from import.meta access
+    }
+    try {
+        // Node.js environment
+        // @ts-expect-error - process may not exist in browser
+        if (typeof process !== 'undefined' && process.env?.NODE_ENV !== undefined) {
+            // @ts-expect-error - accessing process.env
+            return process.env.NODE_ENV !== 'production';
+        }
+    }
+    catch {
+        // Ignore errors from process access
+    }
+    // Default to false (production mode) if we can't determine
+    return false;
+};
+const isDev = getIsDev();
+/**
+ * Validate that a required array prop is non-empty
+ *
+ * @param value - The array to validate
+ * @param propName - Name of the prop for error messages
+ * @param componentName - Name of the component for error messages
+ * @returns Validation result with valid status and optional message
+ *
+ * @example
+ * ```ts
+ * $effect(() => {
+ *   validateNonEmptyArray(options, 'options', 'Select');
+ * });
+ * ```
+ */
+export function validateNonEmptyArray(value, propName, componentName) {
+    if (!isDev)
+        return { valid: true };
+    if (!value || !Array.isArray(value)) {
+        const message = `[${componentName}] "${propName}" is required and must be an array`;
+        console.warn(message);
+        return { valid: false, message };
+    }
+    if (value.length === 0) {
+        const message = `[${componentName}] "${propName}" should not be empty`;
+        console.warn(message);
+        return { valid: false, message };
+    }
+    return { valid: true };
+}
+/**
+ * Validate that a required prop is defined
+ *
+ * @param value - The value to validate
+ * @param propName - Name of the prop for error messages
+ * @param componentName - Name of the component for error messages
+ * @returns Validation result with valid status and optional message
+ *
+ * @example
+ * ```ts
+ * validateRequired(id, 'id', 'FormField');
+ * ```
+ */
+export function validateRequired(value, propName, componentName) {
+    if (!isDev)
+        return { valid: true };
+    if (value === undefined || value === null) {
+        const message = `[${componentName}] "${propName}" is required`;
+        console.warn(message);
+        return { valid: false, message };
+    }
+    return { valid: true };
+}
+/**
+ * Validate prop is one of allowed values
+ *
+ * @param value - The value to validate
+ * @param allowedValues - Array of allowed values
+ * @param propName - Name of the prop for error messages
+ * @param componentName - Name of the component for error messages
+ * @returns Validation result with valid status and optional message
+ *
+ * @example
+ * ```ts
+ * validateOneOf(variant, ['default', 'destructive', 'outline'], 'variant', 'Button');
+ * ```
+ */
+export function validateOneOf(value, allowedValues, propName, componentName) {
+    if (!isDev)
+        return { valid: true };
+    if (!allowedValues.includes(value)) {
+        const message = `[${componentName}] "${propName}" must be one of: ${allowedValues.join(', ')}. Got: ${String(value)}`;
+        console.warn(message);
+        return { valid: false, message };
+    }
+    return { valid: true };
+}
+/**
+ * Validate a number is within a range
+ *
+ * @param value - The number to validate
+ * @param min - Minimum allowed value (inclusive)
+ * @param max - Maximum allowed value (inclusive)
+ * @param propName - Name of the prop for error messages
+ * @param componentName - Name of the component for error messages
+ * @returns Validation result with valid status and optional message
+ */
+export function validateRange(value, min, max, propName, componentName) {
+    if (!isDev)
+        return { valid: true };
+    if (value < min || value > max) {
+        const message = `[${componentName}] "${propName}" must be between ${min} and ${max}. Got: ${value}`;
+        console.warn(message);
+        return { valid: false, message };
+    }
+    return { valid: true };
+}
+/**
+ * Batch validate multiple conditions
+ *
+ * @param validations - Array of validation results
+ * @returns true if all validations pass, false otherwise
+ *
+ * @example
+ * ```ts
+ * const isValid = validateProps([
+ *   validateRequired(id, 'id', 'Component'),
+ *   validateNonEmptyArray(items, 'items', 'Component'),
+ * ]);
+ * ```
+ */
+export function validateProps(validations) {
+    return validations.every((v) => v.valid);
+}
+/**
+ * Create a validator function for a specific component
+ * Useful for creating reusable validation in component files
+ *
+ * @param componentName - Name of the component
+ * @returns Object with bound validation functions
+ *
+ * @example
+ * ```ts
+ * const validate = createValidator('Select');
+ * validate.nonEmptyArray(options, 'options');
+ * validate.required(value, 'value');
+ * ```
+ */
+export function createValidator(componentName) {
+    return {
+        nonEmptyArray: (value, propName) => validateNonEmptyArray(value, propName, componentName),
+        required: (value, propName) => validateRequired(value, propName, componentName),
+        oneOf: (value, allowedValues, propName) => validateOneOf(value, allowedValues, propName, componentName),
+        range: (value, min, max, propName) => validateRange(value, min, max, propName, componentName),
+    };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@classic-homes/theme-svelte",
+  "version": "0.1.0",
+  "description": "Svelte components for the Classic theme system",
+  "type": "module",
+  "svelte": "./dist/lib/index.js",
+  "types": "./dist/lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/lib/index.d.ts",
+      "svelte": "./dist/lib/index.js",
+      "default": "./dist/lib/index.js"
+    },
+    "./styles.css": "./dist/styles.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "svelte-package -i src",
+    "dev": "svelte-package -i src --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json"
+  },
+  "keywords": [
+    "svelte",
+    "components",
+    "design-system"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Classic-Homes/classic-theme.git",
+    "directory": "packages/svelte"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "dependencies": {
+    "@classic-homes/theme-tokens": "*",
+    "bits-ui": "^1.0.0",
+    "clsx": "^2.1.0",
+    "tailwind-merge": "^2.2.0",
+    "tailwind-variants": "^0.3.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.3.0",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "typescript": "^5.3.0"
+  }
+}