sveltacular 1.0.0 → 1.0.4

package/README.md

@@ -12,17 +12,23 @@ npm i sveltacular
 
 ## Quick Start
 
+First, import the default styles to get all CSS variables and base styles:
+
 ```svelte
 <script lang="ts">
+	import 'sveltacular/styles.css';
 	import { Button } from 'sveltacular';
 </script>
 
 <Button variant="primary" label="Hello World" />
 ```
 
+**Note**: The styles import is required for components to render with default styling. If you prefer to provide your own theme, you can skip this import and define your own CSS variables (see [Theming](#theming) below).
+
 ## Component Catalog
 
 ### Forms
+
 - **Button** - Multiple variants (primary, secondary, positive, danger, outline)
 - **TextBox** - Text input with validation and formatting options
 - **NumberBox** - Number input with min/max/decimals
@@ -38,6 +44,7 @@ npm i sveltacular
 - **Form** - Form container with validation
 
 ### Generic Components
+
 - **Card** - Card container
 - **Pill** - Badge/pill component
 - **Badge** - Notification badge
@@ -52,6 +59,7 @@ npm i sveltacular
 - **List** - Styled list component
 
 ### Navigation
+
 - **AppBar** - Application bar
 - **SideBar** - Side navigation
 - **Breadcrumbs** - Breadcrumb navigation
@@ -62,16 +70,19 @@ npm i sveltacular
 - **Drawer** - Slide-out drawer
 
 ### Modals
+
 - **Modal** - Generic modal dialog
 - **Alert** - Alert dialog
 - **Confirm** - Confirmation dialog
 - **Prompt** - Input prompt dialog
 
 ### Tables
+
 - **Table** - Table component with header/body/footer
 - **DataGrid** - Advanced data grid
 
 ### Typography
+
 - **Headline** - Heading component
 - **Subtitle** - Subtitle component
 - **Text** - Text component
@@ -79,6 +90,7 @@ npm i sveltacular
 - **CodeBlock** - Code block
 
 ### Layout
+
 - **FlexRow** / **FlexCol** - Flexbox layout
 - **Grid** - Grid layout
 
@@ -102,11 +114,19 @@ import { CheckBox, CheckBoxGroup } from 'sveltacular/forms/check-box';
 
 ## Theming
 
-Sveltacular uses CSS variables for theming. See [THEMING.md](./THEMING.md) for a complete list of available CSS variables.
+Sveltacular uses CSS variables for theming. When you import `sveltacular/styles.css`, all default CSS variables are included. You can override any of these variables to customize the appearance of components.
+
+See [THEMING.md](./THEMING.md) for a complete list of available CSS variables.
+
+### Customizing the Theme
 
-Example:
+Override CSS variables in your own stylesheet (after importing the default styles):
 
 ```css
+/* Import default styles first */
+@import 'sveltacular/styles.css';
+
+/* Then override variables as needed */
 :root {
 	--button-primary-bg: #1e88e5;
 	--form-input-border: #e0e0e0;
@@ -114,6 +134,27 @@ Example:
 }
 ```
 
+Or in a Svelte component:
+
+```svelte
+<script>
+	import 'sveltacular/styles.css';
+	import { Button } from 'sveltacular';
+</script>
+
+<style>
+	:global(:root) {
+		--button-primary-bg: #1e88e5;
+		--form-input-border: #e0e0e0;
+		--base-color-bg: #ffffff;
+	}
+</style>
+```
+
+### Providing Your Own Theme
+
+If you prefer not to use the default stylesheet, you can define all CSS variables yourself. See [THEMING.md](./THEMING.md) for the complete list of required variables.
+
 ## Form Validation
 
 Sveltacular includes a validation system:
@@ -136,6 +177,7 @@ if (!result.isValid) {
 ## Accessibility
 
 Sveltacular components include:
+
 - ARIA attributes for screen readers
 - Keyboard navigation support
 - Focus management utilities

package/dist/forms/check-box/check-box-group.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
+	import { untrack } from 'svelte';
 	import type { DropdownOption, FormFieldSizeOptions } from '../../types/form.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 	import CheckBox from './check-box.svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
 
@@ -31,13 +31,20 @@
 	// Sync itemsWithState when items or group changes (one-way: items/group -> itemsWithState)
 	// Reassign the entire array to avoid reading itemsWithState in the effect
 	$effect(() => {
-		// Rebuild itemsWithState from items, using group to determine checked state
-		// Reassign instead of mutate to avoid circular dependency
-		const newItems = items.map((item) => ({
-			...item,
-			isChecked: group.includes(item.value ?? '')
-		}));
-		itemsWithState = newItems;
+		// Track items and group as dependencies
+		const currentItems = items;
+		const currentGroup = group;
+		
+		// Use untrack to prevent writing to itemsWithState from triggering this effect again
+		untrack(() => {
+			// Rebuild itemsWithState from items, using group to determine checked state
+			// Reassign instead of mutate to avoid circular dependency
+			const newItems = currentItems.map((item) => ({
+				...item,
+				isChecked: currentGroup.includes(item.value ?? '')
+			}));
+			itemsWithState = newItems;
+		});
 	});
 
 	const handleCheckboxChange = (data: { isChecked: boolean; value: string }) => {
@@ -53,10 +60,7 @@
 	};
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel {id} {required} {label} />
-	{/if}
+<FormField {size} {label} {id} {required} {disabled}>
 	<div>
 		{#each itemsWithState as item}
 			<CheckBox

package/dist/forms/combo-box/combo-box.svelte

@@ -19,9 +19,9 @@
 	 * />
 	 * ```
 	 */
+	import { untrack } from 'svelte';
 	import type { DropdownOption, FormFieldSizeOptions } from '../../types/form.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
 	import Menu from '../../generic/menu/menu.svelte';
 	import AngleUpIcon from '../../icons/angle-up-icon.svelte';
@@ -40,7 +40,7 @@
 		multiSelect = false,
 		placeholder = '',
 		label = undefined,
-		helpText = undefined,
+		helperText = undefined,
 		errorText = undefined,
 		successText = undefined,
 		maxSelections = undefined as number | undefined,
@@ -68,8 +68,8 @@
 		placeholder?: string;
 		/** Label text for the combobox */
 		label?: string;
-		/** Help text displayed below the input */
-		helpText?: string;
+		/** Helper text displayed below the input */
+		helperText?: string;
 		/** Error message to display */
 		errorText?: string;
 		/** Success message to display */
@@ -368,9 +368,28 @@
 		}
 	};
 
-	// Initial filter
+	// Filter items when items or searchQuery changes
+	// Use untrack to prevent reading filteredItems/highlightIndex from triggering the effect
 	$effect(() => {
-		applyFilter();
+		// Track only the dependencies we care about
+		const query = searchQuery.trim().toLowerCase();
+		const currentItems = items;
+		
+		// Use untrack to write to state without triggering this effect again
+		untrack(() => {
+			if (query && searchable) {
+				filteredItems = currentItems.filter((item) =>
+					item.name.toLowerCase().includes(query)
+				);
+			} else {
+				filteredItems = [...currentItems];
+			}
+
+			// Reset highlight if out of bounds
+			if (highlightIndex >= filteredItems.length) {
+				highlightIndex = Math.max(0, filteredItems.length - 1);
+			}
+		});
 	});
 
 	// Derived state for open/closed
@@ -379,16 +398,15 @@
 	// Clear search query when menu closes in single-select mode
 	$effect(() => {
 		if (!isMenuOpen && !multiSelect) {
-			searchQuery = '';
+			// Use untrack to prevent triggering other effects
+			untrack(() => {
+				searchQuery = '';
+			});
 		}
 	});
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel {id} {required} {disabled} {label} />
-	{/if}
-
+<FormField {size} {label} {id} {required} {disabled} {helperText} {errorText} {successText}>
 	<div class="combobox-wrapper {open ? 'open' : 'closed'} {disabled ? 'disabled' : 'enabled'}">
 		<!-- Multi-select chip display -->
 		{#if multiSelect && selectedItems.length > 0}
@@ -423,7 +441,7 @@
 				aria-activedescendant={activeDescendant}
 				aria-haspopup="listbox"
 				aria-label={label}
-				aria-describedby={helpText || errorText || successText ? `${id}-description` : undefined}
+				aria-describedby={helperText || errorText || successText ? `${id}-helper ${id}-error ${id}-success` : undefined}
 				aria-invalid={errorText ? 'true' : undefined}
 				onfocus={() => {
 					if (!disabled) {
@@ -489,19 +507,6 @@
 		</div>
 	</div>
 
-	<!-- Help/Error/Success text -->
-	{#if helpText || errorText || successText}
-		<div id="{id}-description" class="description">
-			{#if errorText}
-				<span class="error-text" role="alert">{errorText}</span>
-			{:else if successText}
-				<span class="success-text" role="status">{successText}</span>
-			{:else if helpText}
-				<span class="help-text">{helpText}</span>
-			{/if}
-		</div>
-	{/if}
-
 	<!-- Max selections indicator -->
 	{#if multiSelect && maxSelections !== undefined}
 		<div class="max-selections-indicator">
@@ -629,23 +634,6 @@ button:focus-visible {
   margin-top: 0.25rem;
 }
 
-.description {
-  margin-top: 0.5rem;
-  font-size: var(--font-sm);
-  line-height: 1.4;
-}
-.description .help-text {
-  color: var(--gray-600);
-}
-.description .error-text {
-  color: var(--danger);
-  font-weight: 500;
-}
-.description .success-text {
-  color: var(--success);
-  font-weight: 500;
-}
-
 .max-selections-indicator {
   margin-top: 0.5rem;
   font-size: var(--font-sm);

package/dist/forms/combo-box/combo-box.svelte.d.ts

@@ -1,23 +1,3 @@
-/**
-     * Combobox Component
-     *
-     * A searchable select component with typeahead, multi-select support, and virtual scrolling.
-     * Follows the ARIA 1.2 Combobox pattern for full accessibility.
-     *
-     * @component
-     * @example
-     * ```svelte
-     * <ComboBox
-     *   bind:value
-     *   items={[
-     *     { value: '1', name: 'Option 1' },
-     *     { value: '2', name: 'Option 2' }
-     *   ]}
-     *   label="Select an option"
-     *   searchable
-     * />
-     * ```
-     */
 import type { DropdownOption, FormFieldSizeOptions } from '../../types/form.js';
 type $$ComponentProps = {
     /** Current selected value(s) - string for single-select, string[] for multi-select */
@@ -38,8 +18,8 @@ type $$ComponentProps = {
     placeholder?: string;
     /** Label text for the combobox */
     label?: string;
-    /** Help text displayed below the input */
-    helpText?: string;
+    /** Helper text displayed below the input */
+    helperText?: string;
     /** Error message to display */
     errorText?: string;
     /** Success message to display */

package/dist/forms/date-box/date-box.svelte

@@ -1,8 +1,8 @@
 <script lang="ts">
+	import { untrack } from 'svelte';
 	import { addUnits, currentDateTime, isDateString, isDateOrDateTimeString, isDateTimeString } from '../../helpers/date.js';
 	import { uniqueId } from '../../helpers/unique-id.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 	import type { DateUnit, FormFieldSizeOptions } from '../../index.js';
 	import Button from '../button/button.svelte';
 
@@ -68,17 +68,17 @@
 
 	$effect(() => {
 		if (!value) {
-			if (nullable) enabled = false;
-			else value = getDefaultValue();
+			// Use untrack to prevent writes to enabled/value from triggering this effect again
+			untrack(() => {
+				if (nullable) enabled = false;
+				else value = getDefaultValue();
+			});
 		}
 	});
 	let disabled = $derived(!enabled);
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel {id} {required} {label} />
-	{/if}
+<FormField {size} {label} {id} {required} {disabled}>
 	<div class:nullable class:disabled>
 		<span class="input">
 			<input {...{ type }} {id} {placeholder} {disabled} bind:value {required} oninput={onInput} />

package/dist/forms/file-box/file-box.svelte

@@ -2,7 +2,6 @@
 	import type { Snippet } from 'svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 	import type { FormFieldSizeOptions } from '../../types/form.js';
 
 	const id = uniqueId();
@@ -32,10 +31,7 @@
 	} = $props();
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel {id} {required} {label} />
-	{/if}
+<FormField {size} {label} {id} {required} {disabled}>
 	<div>
 		<input
 			{id}

package/dist/forms/form-field.svelte

@@ -2,24 +2,82 @@
 	import type { Snippet } from 'svelte';
 	import type { ComponentSize } from '../types/size.js';
 	import { getMaxWidth, getDisplayType } from '../types/size.js';
+	import FormLabel from './form-label.svelte';
 
 	let {
 		size = 'full',
+		label = undefined,
+		id = undefined,
+		required = false,
+		disabled = false,
+		helperText = undefined,
+		errorText = undefined,
+		successText = undefined,
 		children
 	}: {
 		size?: ComponentSize;
+		label?: string | undefined;
+		id?: string | undefined;
+		required?: boolean;
+		disabled?: boolean;
+		helperText?: string | undefined;
+		errorText?: string | undefined;
+		successText?: string | undefined;
 		children: Snippet;
 	} = $props();
 
 	let displayType = $derived(getDisplayType(size));
 	let maxWidth = $derived(getMaxWidth(size));
+
+	let showHelperText = $derived(!!helperText && !errorText && !successText);
+	let showSuccessText = $derived(!!successText && !errorText);
+	let showErrorText = $derived(!!errorText);
 </script>
 
 <div style={`display: ${displayType}; width: 100%; min-width: 10rem; max-width: ${maxWidth}`}>
+	{#if label}
+		<FormLabel {id} {required} {disabled} {label} />
+	{/if}
 	{@render children?.()}
+	{#if showHelperText}
+		<div class="helper-text" id="{id}-helper">{helperText}</div>
+	{/if}
+	{#if showSuccessText}
+		<div class="success-text" id="{id}-success" role="status" aria-live="polite">
+			{successText}
+		</div>
+	{/if}
+	{#if showErrorText}
+		<div class="error-text" id="{id}-error" role="alert" aria-live="assertive">
+			{errorText}
+		</div>
+	{/if}
 </div>
 
 <style>div {
   margin-bottom: var(--spacing-base);
   margin-right: var(--spacing-base);
+}
+
+.helper-text {
+  font-size: var(--font-sm);
+  line-height: 1.25rem;
+  padding: var(--spacing-xs);
+  color: var(--body-fg);
+}
+
+.success-text {
+  font-size: var(--font-sm);
+  line-height: 1.25rem;
+  padding: var(--spacing-xs);
+  color: var(--success, #28a745);
+  font-weight: 500;
+}
+
+.error-text {
+  font-size: var(--font-sm);
+  line-height: 1.25rem;
+  padding: var(--spacing-xs);
+  color: var(--danger, #dc3545);
+  font-weight: 500;
 }</style>

package/dist/forms/form-field.svelte.d.ts

@@ -2,6 +2,13 @@ import type { Snippet } from 'svelte';
 import type { ComponentSize } from '../types/size.js';
 type $$ComponentProps = {
     size?: ComponentSize;
+    label?: string | undefined;
+    id?: string | undefined;
+    required?: boolean;
+    disabled?: boolean;
+    helperText?: string | undefined;
+    errorText?: string | undefined;
+    successText?: string | undefined;
     children: Snippet;
 };
 declare const FormField: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/forms/form-row.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+
+	interface Props {
+		children: Snippet;
+	}
+
+	let { children }: Props = $props();
+</script>
+
+<div class="form-row">
+	{@render children()}
+</div>
+
+<style>/* ============================================
+   BREAKPOINTS - Responsive Design
+   ============================================ */
+.form-row {
+  display: flex;
+  flex-direction: row;
+  gap: var(--spacing-base);
+  align-items: flex-start;
+}
+@media (max-width: 479.98px) {
+  .form-row {
+    flex-direction: column;
+    align-items: stretch;
+  }
+}</style>

package/dist/forms/form-row.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    children: Snippet;
+}
+declare const FormRow: import("svelte").Component<Props, {}, "">;
+type FormRow = ReturnType<typeof FormRow>;
+export default FormRow;

package/dist/forms/form.svelte

@@ -33,3 +33,9 @@
 		{@render children()}
 	</form>
 </Section>
+
+<style>form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-base);
+}</style>

package/dist/forms/info-box/info-box.svelte

@@ -2,7 +2,6 @@
 	import LinkIcon from '../../icons/link-icon.svelte';
 	import type { FormFieldSizeOptions } from '../../index.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 
 	let {
 		size = 'md' as FormFieldSizeOptions,
@@ -17,10 +16,7 @@
 	} = $props();
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel {label} />
-	{/if}
+<FormField {size} {label}>
 	<div class="input">
 		{#if href}
 			<span class="icon">

package/dist/forms/list-box/list-box.svelte

@@ -1,7 +1,6 @@
 <script lang="ts">
 	import type { DropdownOption, FormFieldSizeOptions, MenuOption } from '../../types/form.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
 	import Menu from '../../generic/menu/menu.svelte';
 	import AngleUpIcon from '../../icons/angle-up-icon.svelte';
@@ -151,10 +150,7 @@
 	let open = $derived(isMenuOpen && !disabled);
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel {id} {required} {disabled} {label} />
-	{/if}
+<FormField {size} {label} {id} {required} {disabled}>
 	<div class="{open ? 'open' : 'closed'} {disabled ? 'disabled' : 'enabled'}">
 		<input
 			type="text"

package/dist/forms/money-box/money-box.svelte

@@ -1,7 +1,6 @@
 <script lang="ts">
 	import { uniqueId, type FormFieldSizeOptions } from '../../index.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 	import { untrack } from 'svelte';
 	
 	const id = uniqueId();
@@ -58,8 +57,11 @@
 	]);
 	$effect(() => {
 		if (value !== null && value >= 0) {
-			dollars = getDollarsFromValue();
-			cents = getCentsFromValue();
+			// Use untrack to prevent writes to dollars/cents from triggering this effect again
+			untrack(() => {
+				dollars = getDollarsFromValue();
+				cents = getCentsFromValue();
+			});
 		}
 	});
 
@@ -207,10 +209,7 @@
 
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel {id} {label} />
-	{/if}
+<FormField {size} {label} {id}>
 	<div class="input {currency}" class:allowCents {id}>
 		{#if prefix}
 			<span class="prefix">{prefix}</span>

package/dist/forms/number-box/number-box.svelte

@@ -2,7 +2,6 @@
 	import { roundToDecimals } from '../../helpers/round-to-decimals.js';
 	import { uniqueId } from '../../helpers/unique-id.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 	import type { FormFieldSizeOptions } from '../../types/form.js';
 	const id = uniqueId();
 
@@ -64,10 +63,7 @@
 	};
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel {id} {label} />
-	{/if}
+<FormField {size} {label} {id}>
 	<div class="input {type}">
 		{#if prefix}
 			<span class="prefix">{prefix}</span>

package/dist/forms/phone-box/phone-box.svelte

@@ -1,7 +1,7 @@
 <script lang="ts">
+	import { untrack } from 'svelte';
 	import { uniqueId, type FormFieldSizeOptions } from '../../index.js';
 	import FormField from '../form-field.svelte';
-	import FormLabel from '../form-label.svelte';
 
 	let {
 		value = $bindable('' as string | null),
@@ -135,16 +135,18 @@
 	setValue(value ?? '');
 
 	$effect(() => {
-		if (areaCode || localExt || lastFour) {
-			publishChange();
+		// Only trigger when the phone number parts change
+		const hasValue = areaCode || localExt || lastFour;
+		if (hasValue) {
+			// Use untrack to prevent value changes from triggering this effect again
+			untrack(() => {
+				publishChange();
+			});
 		}
 	});
 </script>
 
-<FormField {size}>
-	{#if label}
-		<FormLabel id="{id}-areaCode" {label} />
-	{/if}
+<FormField {size} {label} id="{id}-areaCode">
 	<div class="input">
 		<span class="areaCode segment">
 			<span>(</span>