sveltacular 1.0.1 → 1.0.5

package/README.md

@@ -12,6 +12,28 @@ npm i sveltacular
 
 ## Quick Start
 
+### 1. Import the default stylesheet (once, in your app root)
+
+**For SvelteKit**, add this to `src/routes/+layout.svelte`:
+
+```svelte
+<script lang="ts">
+	import 'sveltacular/styles.css';
+</script>
+
+<slot />
+```
+
+**For regular Svelte**, add it to your main `App.svelte` or root component:
+
+```svelte
+<script lang="ts">
+	import 'sveltacular/styles.css';
+</script>
+```
+
+### 2. Use components anywhere
+
 ```svelte
 <script lang="ts">
 	import { Button } from 'sveltacular';
@@ -20,9 +42,12 @@ npm i sveltacular
 <Button variant="primary" label="Hello World" />
 ```
 
+**Note**: The stylesheet import is required for components to render with default styling. Import it once at the app level (not in individual components). 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 +63,7 @@ npm i sveltacular
 - **Form** - Form container with validation
 
 ### Generic Components
+
 - **Card** - Card container
 - **Pill** - Badge/pill component
 - **Badge** - Notification badge
@@ -52,6 +78,7 @@ npm i sveltacular
 - **List** - Styled list component
 
 ### Navigation
+
 - **AppBar** - Application bar
 - **SideBar** - Side navigation
 - **Breadcrumbs** - Breadcrumb navigation
@@ -62,16 +89,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 +109,7 @@ npm i sveltacular
 - **CodeBlock** - Code block
 
 ### Layout
+
 - **FlexRow** / **FlexCol** - Flexbox layout
 - **Grid** - Grid layout
 
@@ -102,11 +133,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.
 
-Example:
+See [THEMING.md](./THEMING.md) for a complete list of available CSS variables.
+
+### Customizing the Theme
+
+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 +153,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 +196,7 @@ if (!result.isValid) {
 ## Accessibility
 
 Sveltacular components include:
+
 - ARIA attributes for screen readers
 - Keyboard navigation support
 - Focus management utilities

package/dist/forms/base-input-wrapper.svelte

@@ -1,6 +1,5 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
-	import type { FormFieldSizeOptions } from '../types/form.js';
 
 	let {
 		id,
@@ -96,4 +95,3 @@
   padding: var(--spacing-xs);
   color: var(--form-input-error-fg);
 }</style>
-

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 FormField from '../form-field/form-field.svelte';
 	import CheckBox from './check-box.svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
 
@@ -34,7 +34,7 @@
 		// 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

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

@@ -1,12 +1,18 @@
 <script lang="ts">
 	import { untrack } from 'svelte';
-	import { addUnits, currentDateTime, isDateString, isDateOrDateTimeString, isDateTimeString } from '../../helpers/date.js';
+	import {
+		addUnits,
+		currentDateTime,
+		isDateString,
+		isDateOrDateTimeString,
+		isDateTimeString
+	} from '../../helpers/date.js';
 	import { uniqueId } from '../../helpers/unique-id.js';
-	import FormField from '../form-field.svelte';
+	import FormField from '../form-field/form-field.svelte';
 	import type { DateUnit, FormFieldSizeOptions } from '../../index.js';
 	import Button from '../button/button.svelte';
 
-	type DateIncrementStep = { label: string; value: number, unit: DateUnit };
+	type DateIncrementStep = { label: string; value: number; unit: DateUnit };
 
 	const id = uniqueId();
 
@@ -91,7 +97,12 @@
 		{#if steps.length > 0}
 			<span class="steps">
 				{#each steps as step}
-					<Button noMargin={true} collapse={true} onClick={() => incrementValue(step)} label={step.label} />
+					<Button
+						noMargin={true}
+						collapse={true}
+						onClick={() => incrementValue(step)}
+						label={step.label}
+					/>
 				{/each}
 			</span>
 		{/if}

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

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
-	import FormField from '../form-field.svelte';
+	import FormField from '../form-field/form-field.svelte';
 	import type { FormFieldSizeOptions } from '../../types/form.js';
 
 	const id = uniqueId();

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

@@ -0,0 +1,86 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { ComponentSize } from '../../types/size.js';
+	import { getMaxWidth, getDisplayType } from '../../types/size.js';
+	import FormLabel from '../form-label/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 class="form-field {size} {displayType} {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>/* ============================================
+   BREAKPOINTS - Responsive Design
+   ============================================ */
+.form-field {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  flex: 1;
+}
+@media (max-width: 479.98px) {
+  .form-field {
+    width: 100%;
+  }
+}
+
+.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/form-field.svelte.d.ts

@@ -0,0 +1,16 @@
+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, {}, "">;
+type FormField = ReturnType<typeof FormField>;
+export default FormField;

package/dist/forms/form-footer.svelte

@@ -1,18 +1,20 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
-	import FlexRow from '../layout/flex-row.svelte';
 
 	let { children }: { children: Snippet } = $props();
 </script>
 
 <div>
-	<FlexRow justifyContent="stretch">
-		{@render children?.()}
-	</FlexRow>
+	{@render children?.()}
 </div>
 
 <style>
 	div {
-		margin-top: 1.5rem;
+		display: flex;
+		flex-direction: row;
+		gap: var(--spacing-base);
+		justify-content: flex-end;
+		margin-top: var(--spacing-lg);
+		margin-top: var(--spacing-xl);
 	}
 </style>

package/dist/forms/form-label/form-label.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	let {
+		id = undefined,
+		required = false,
+		disabled = false,
+		label = ''
+	}: {
+		id?: string | undefined;
+		required?: boolean;
+		disabled?: boolean;
+		label?: string;
+	} = $props();
+</script>
+
+<label for={id} class:required class:disabled aria-required={required}>{label}</label>
+
+<style>label {
+  display: block;
+  margin-bottom: var(--spacing-sm);
+  font-weight: 500;
+  font-size: var(--font-base);
+}
+label.required::after {
+  content: "*";
+  margin-left: var(--spacing-xs);
+}
+label.disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}</style>

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

@@ -0,0 +1,9 @@
+type $$ComponentProps = {
+    id?: string | undefined;
+    required?: boolean;
+    disabled?: boolean;
+    label?: string;
+};
+declare const FormLabel: import("svelte").Component<$$ComponentProps, {}, "">;
+type FormLabel = ReturnType<typeof FormLabel>;
+export default FormLabel;

package/dist/forms/form-row/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/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-section/form-section.svelte

@@ -0,0 +1,36 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { SectionLevel } from '../../types/generic.js';
+
+	let {
+		title = undefined,
+		level = 4,
+		children
+	}: {
+		title?: string | undefined;
+		level?: SectionLevel;
+		children: Snippet;
+	} = $props();
+</script>
+
+<fieldset>
+	{#if title}
+		<legend aria-level={level}>{title}</legend>
+	{/if}
+	{@render children?.()}
+</fieldset>
+
+<style>fieldset {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-base);
+  border: var(--border-thin) solid var(--form-input-border);
+  border-radius: var(--radius-md);
+  padding: var(--spacing-base);
+}
+fieldset legend {
+  font-size: var(--font-lg);
+  font-weight: 500;
+  line-height: var(--line-height-base);
+  color: var(--form-input-fg);
+}</style>

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

@@ -0,0 +1,10 @@
+import type { Snippet } from 'svelte';
+import type { SectionLevel } from '../../types/generic.js';
+type $$ComponentProps = {
+    title?: string | undefined;
+    level?: SectionLevel;
+    children: Snippet;
+};
+declare const FormSection: import("svelte").Component<$$ComponentProps, {}, "">;
+type FormSection = ReturnType<typeof FormSection>;
+export default FormSection;

package/dist/forms/index.d.ts

@@ -11,16 +11,16 @@ export { default as TextArea } from './text-area/text-area.svelte';
 export { default as TextBox } from './text-box/text-box.svelte';
 export { default as UrlBox } from './url-box/url-box.svelte';
 export * from './check-box/index.js';
-export * from './combo-box/index.js';
 export * from './list-box/index.js';
 export * from './phone-box/index.js';
 export * from './radio-group/index.js';
 export { default as Form } from './form.svelte';
-export { default as FormField } from './form-field.svelte';
+export { default as FormField } from './form-field/form-field.svelte';
 export { default as FormFooter } from './form-footer.svelte';
 export { default as FormHeader } from './form-header.svelte';
-export { default as FormLabel } from './form-label.svelte';
-export { default as FormSection } from './form-section.svelte';
+export { default as FormLabel } from './form-label/form-label.svelte';
+export { default as FormSection } from './form-section/form-section.svelte';
+export { default as FormRow } from './form-row/form-row.svelte';
 export { default as Slider } from './slider/slider.svelte';
 export { default as TimeBox } from './time-box/time-box.svelte';
 export * from './validation.js';

package/dist/forms/index.js

@@ -13,17 +13,17 @@ export { default as TextBox } from './text-box/text-box.svelte';
 export { default as UrlBox } from './url-box/url-box.svelte';
 // Form components with barrel files
 export * from './check-box/index.js';
-export * from './combo-box/index.js';
 export * from './list-box/index.js';
 export * from './phone-box/index.js';
 export * from './radio-group/index.js';
 // Form structure components
 export { default as Form } from './form.svelte';
-export { default as FormField } from './form-field.svelte';
+export { default as FormField } from './form-field/form-field.svelte';
 export { default as FormFooter } from './form-footer.svelte';
 export { default as FormHeader } from './form-header.svelte';
-export { default as FormLabel } from './form-label.svelte';
-export { default as FormSection } from './form-section.svelte';
+export { default as FormLabel } from './form-label/form-label.svelte';
+export { default as FormSection } from './form-section/form-section.svelte';
+export { default as FormRow } from './form-row/form-row.svelte';
 // New form components
 export { default as Slider } from './slider/slider.svelte';
 export { default as TimeBox } from './time-box/time-box.svelte';

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

@@ -1,7 +1,7 @@
 <script lang="ts">
 	import LinkIcon from '../../icons/link-icon.svelte';
 	import type { FormFieldSizeOptions } from '../../index.js';
-	import FormField from '../form-field.svelte';
+	import FormField from '../form-field/form-field.svelte';
 
 	let {
 		size = 'md' as FormFieldSizeOptions,

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

@@ -1,6 +1,6 @@
 <script lang="ts">
 	import type { DropdownOption, FormFieldSizeOptions, MenuOption } from '../../types/form.js';
-	import FormField from '../form-field.svelte';
+	import FormField from '../form-field/form-field.svelte';
 	import { uniqueId } from '../../helpers/unique-id.js';
 	import Menu from '../../generic/menu/menu.svelte';
 	import AngleUpIcon from '../../icons/angle-up-icon.svelte';
@@ -45,7 +45,7 @@
 	let highlightIndex = $state(-1);
 	let filteredItems = $state<MenuOption[]>([]);
 	let isSeachable = $derived(searchable || !!search);
-	
+
 	// Get the ID of the highlighted option for ARIA
 	let activeDescendant = $derived(
 		highlightIndex >= 0 && filteredItems[highlightIndex]
@@ -201,7 +201,7 @@
 				{open}
 				closeAfterSelect={false}
 				searchText={text}
-				onSelect={onSelect}
+				{onSelect}
 				size="full"
 				bind:highlightIndex
 				bind:value

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

@@ -1,8 +1,8 @@
 <script lang="ts">
 	import { uniqueId, type FormFieldSizeOptions } from '../../index.js';
-	import FormField from '../form-field.svelte';
+	import FormField from '../form-field/form-field.svelte';
 	import { untrack } from 'svelte';
-	
+
 	const id = uniqueId();
 
 	let {
@@ -35,18 +35,18 @@
 
 	let isValueInCents = $derived(units === 'cents');
 	const fieldOrder = ['dollars', 'cents'];
-	
+
 	const getDollarsFromValue = () => {
 		if (!value) return '0';
 		if (isValueInCents) return String(Math.abs(Math.floor(value / 100)));
 		return String(Math.abs(Math.floor(value)));
-	}
+	};
 
 	const getCentsFromValue = () => {
 		if (!value) return '00';
 		if (isValueInCents) return String(Math.abs(Math.round(value % 100))).padStart(2, '0');
 		return String(Math.abs(Math.round((value % 1) * 100))).padStart(2, '0');
-	}
+	};
 
 	let dollars = $state(getDollarsFromValue());
 	let cents = $state(getCentsFromValue());
@@ -74,9 +74,10 @@
 		const selection = [target.selectionStart ?? 0, target.selectionEnd ?? 0];
 		const key = e instanceof KeyboardEvent ? e.key : '';
 		const isNumber = !isNaN(Number(key));
-		const isDecimal =key === '.';
+		const isDecimal = key === '.';
 		const isBackspace = key === 'Backspace';
-		const isAllowed = isNumber || isDecimal || ['Delete', 'ArrowLeft', 'ArrowRight', 'Tab'].includes(key);
+		const isAllowed =
+			isNumber || isDecimal || ['Delete', 'ArrowLeft', 'ArrowRight', 'Tab'].includes(key);
 		return {
 			element: target,
 			name,
@@ -91,8 +92,8 @@
 			isAllowed,
 			lastState: lastState[index],
 			value: target.value,
-			next: nextName ? document.getElementById(`${id}-${nextName}`) as HTMLInputElement : null,
-			previous: prevName ? document.getElementById(`${id}-${prevName}`) as HTMLInputElement : null
+			next: nextName ? (document.getElementById(`${id}-${nextName}`) as HTMLInputElement) : null,
+			previous: prevName ? (document.getElementById(`${id}-${prevName}`) as HTMLInputElement) : null
 		};
 	};
 
@@ -116,8 +117,8 @@
 
 	const moveExtraCentsToDollars = (centsValue: string, append = true) => {
 		if (centsValue.length > 2 && isNumericString(centsValue) && Number(centsValue) > 0) {
-			const whole = centsValue.substring(0, centsValue.length -2);
-			const decimal = centsValue.substring(centsValue.length -2);
+			const whole = centsValue.substring(0, centsValue.length - 2);
+			const decimal = centsValue.substring(centsValue.length - 2);
 			dollars = append ? `${dollars}${whole}` : whole;
 			cents = decimal;
 		}
@@ -130,7 +131,7 @@
 			e.preventDefault();
 			if (target.next && allowCents) focusAndHighlightText(target.next);
 			return;
-		};
+		}
 		if (target.name === 'cents' && target.value.length >= 2 && !target.isHighligted) {
 			if (target.isNumber) moveExtraCentsToDollars(`${target.value}${e.key}`);
 			return e.preventDefault();
@@ -141,14 +142,24 @@
 	const onKeyUp = (e: KeyboardEvent) => {
 		const target = getTargetProperties(e);
 		// Back arrow
-		if (target.key === 'ArrowLeft' && !target.isHighligted && target.previous && target.lastState.selectionStart === 0) {
+		if (
+			target.key === 'ArrowLeft' &&
+			!target.isHighligted &&
+			target.previous &&
+			target.lastState.selectionStart === 0
+		) {
 			const preservedValue = String(target.previous.value);
 			focusAndHighlightText(target.previous);
 			target.previous.value = preservedValue;
 			return e.preventDefault();
 		}
 		// Right arrow
-		if (target.key === 'ArrowRight' && !target.isHighligted && target.next && target.lastState.selectionStart === target.value.length) {
+		if (
+			target.key === 'ArrowRight' &&
+			!target.isHighligted &&
+			target.next &&
+			target.lastState.selectionStart === target.value.length
+		) {
 			focusAndHighlightText(target.next);
 			return e.preventDefault();
 		}
@@ -197,8 +208,8 @@
 		let centValue = Math.abs(isNumericString(cents) ? Number(cents) : 0);
 		let dollarValue = Math.abs(isNumericString(dollars) ? Number(dollars) : 0);
 		// Update value
-		if (isValueInCents) value = (dollarValue * 100) + centValue;
-		else value = dollarValue + (centValue / 100);
+		if (isValueInCents) value = dollarValue * 100 + centValue;
+		else value = dollarValue + centValue / 100;
 		// Enforce min and max
 		if (min && value < min) value = min;
 		if (max && value > max) value = max;
@@ -206,7 +217,6 @@
 		cents = String(centValue).padStart(2, '0');
 		onChange?.(value);
 	};
-
 </script>
 
 <FormField {size} {label} {id}>