alus-ui 0.1.0

package/dist/utils/a11y/focus.js

@@ -0,0 +1,91 @@
+/**
+ * Focus management utilities for accessibility
+ */
+/**
+ * Traps focus within a container (for modals, dialogs, dropdowns)
+ * Returns a cleanup function that removes the event listener
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { focus } from 'alus-ui';
+ *   let modalElement;
+ *
+ *   function openModal() {
+ *     modalElement.showModal();
+ *     const cleanup = focus.trap(modalElement);
+ *     // Store cleanup to call when modal closes
+ *   }
+ * </script>
+ *
+ * <dialog bind:this={modalElement}>
+ *   <!-- Content -->
+ * </dialog>
+ * ```
+ */
+export function trap(container) {
+    const focusableElements = container.querySelectorAll('a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])');
+    const firstElement = focusableElements[0];
+    const lastElement = focusableElements[focusableElements.length - 1];
+    const handleTabKey = (e) => {
+        if (e.key !== 'Tab')
+            return;
+        if (e.shiftKey) {
+            if (document.activeElement === firstElement) {
+                e.preventDefault();
+                lastElement?.focus();
+            }
+        }
+        else {
+            if (document.activeElement === lastElement) {
+                e.preventDefault();
+                firstElement?.focus();
+            }
+        }
+    };
+    container.addEventListener('keydown', handleTabKey);
+    return () => container.removeEventListener('keydown', handleTabKey);
+}
+/**
+ * Moves focus to first focusable element in container
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { focus } from 'alus-ui';
+ *   let dialogElement;
+ *
+ *   function open() {
+ *     dialogElement.showModal();
+ *     focus.focusFirst(dialogElement);
+ *   }
+ * </script>
+ * ```
+ */
+export function focusFirst(container) {
+    const focusable = container.querySelector('a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])');
+    focusable?.focus();
+}
+/**
+ * Moves focus to last focusable element in container
+ */
+export function focusLast(container) {
+    const focusable = container.querySelectorAll('a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])');
+    const last = focusable[focusable.length - 1];
+    last?.focus();
+}
+/**
+ * Checks if an element can receive focus
+ */
+export function isFocusable(element) {
+    if (element instanceof HTMLButtonElement ||
+        element instanceof HTMLInputElement ||
+        element instanceof HTMLSelectElement ||
+        element instanceof HTMLTextAreaElement) {
+        return !element.disabled && element.tabIndex >= 0;
+    }
+    if (element instanceof HTMLAnchorElement) {
+        return element.href !== '';
+    }
+    return element.tabIndex >= 0;
+}

package/dist/utils/a11y/id.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ID generation utilities for accessibility associations
+ */
+/**
+ * Creates a unique ID for accessibility associations
+ * Useful for generating IDs for aria-describedby, aria-labelledby, etc.
+ *
+ * @param prefix - Descriptive prefix for the ID (e.g., 'label', 'desc', 'error')
+ * @returns A unique ID string
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { generateId } from 'alus-ui';
+ *
+ *   const labelId = generateId('label');
+ *   const errorId = generateId('error');
+ * </script>
+ *
+ * <Input id="email" {...labelAttrs({ labelledby: labelId, describedby: errorId })} />
+ * <label {for}>Email</label>
+ * <p id={errorId} role="alert">{error}</p>
+ * ```
+ */
+export declare function generateId(prefix: string): string;
+/**
+ * Creates a sequential ID (useful for lists, radios, checkboxes)
+ *
+ * @param prefix - Descriptive prefix for the ID
+ * @returns A sequential ID string
+ *
+ * @example
+ * ```svelte
+ * {#each items as item, i}
+ *   <Radio id={generateSequentialId('option', i)} />
+ * {/each}
+ * ```
+ */
+export declare function generateSequentialId(prefix: string, index: number): string;
+/**
+ * Creates a counter-based ID (guaranteed unique per session)
+ *
+ * @param prefix - Descriptive prefix for the ID
+ * @returns A unique counter-based ID
+ */
+export declare function generateCounterId(prefix: string): string;
+/**
+ * ID generation utilities object
+ */
+export declare const id: {
+    generate: typeof generateId;
+    sequential: typeof generateSequentialId;
+    counter: typeof generateCounterId;
+};

package/dist/utils/a11y/id.js

@@ -0,0 +1,61 @@
+/**
+ * ID generation utilities for accessibility associations
+ */
+let counter = 0;
+/**
+ * Creates a unique ID for accessibility associations
+ * Useful for generating IDs for aria-describedby, aria-labelledby, etc.
+ *
+ * @param prefix - Descriptive prefix for the ID (e.g., 'label', 'desc', 'error')
+ * @returns A unique ID string
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { generateId } from 'alus-ui';
+ *
+ *   const labelId = generateId('label');
+ *   const errorId = generateId('error');
+ * </script>
+ *
+ * <Input id="email" {...labelAttrs({ labelledby: labelId, describedby: errorId })} />
+ * <label {for}>Email</label>
+ * <p id={errorId} role="alert">{error}</p>
+ * ```
+ */
+export function generateId(prefix) {
+    return `alus-${prefix}-${Math.random().toString(36).substring(2, 9)}`;
+}
+/**
+ * Creates a sequential ID (useful for lists, radios, checkboxes)
+ *
+ * @param prefix - Descriptive prefix for the ID
+ * @returns A sequential ID string
+ *
+ * @example
+ * ```svelte
+ * {#each items as item, i}
+ *   <Radio id={generateSequentialId('option', i)} />
+ * {/each}
+ * ```
+ */
+export function generateSequentialId(prefix, index) {
+    return `alus-${prefix}-${index}`;
+}
+/**
+ * Creates a counter-based ID (guaranteed unique per session)
+ *
+ * @param prefix - Descriptive prefix for the ID
+ * @returns A unique counter-based ID
+ */
+export function generateCounterId(prefix) {
+    return `alus-${prefix}-${counter++}`;
+}
+/**
+ * ID generation utilities object
+ */
+export const id = {
+    generate: generateId,
+    sequential: generateSequentialId,
+    counter: generateCounterId
+};

package/dist/utils/a11y/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Accessibility utilities for WCAG compliance and ARIA attributes
+ * @module a11y
+ */
+export * from './aria.js';
+export * from './focus.js';
+export * from './keyboard.js';
+export * from './id.js';

package/dist/utils/a11y/index.js

@@ -0,0 +1,12 @@
+/**
+ * Accessibility utilities for WCAG compliance and ARIA attributes
+ * @module a11y
+ */
+// Export all ARIA utilities
+export * from './aria.js';
+// Export focus management
+export * from './focus.js';
+// Export keyboard utilities
+export * from './keyboard.js';
+// Export ID generation
+export * from './id.js';

package/dist/utils/a11y/keyboard.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Keyboard event utilities for accessibility
+ */
+/**
+ * Checks if Enter or Space was pressed (for button-like behavior)
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { keyboard } from 'alus-ui';
+ *
+ *   function handleKeydown(e: KeyboardEvent) {
+ *     if (keyboard.isActivationKey(e)) {
+ *       // Activate button
+ *     }
+ *   }
+ * </script>
+ * ```
+ */
+export declare function isActivationKey(event: KeyboardEvent): boolean;
+/**
+ * Checks if Escape was pressed
+ */
+export declare function isEscape(event: KeyboardEvent): boolean;
+/**
+ * Checks if Arrow key was pressed
+ */
+export declare function isArrow(event: KeyboardEvent): boolean;
+/**
+ * Checks if Home or End was pressed
+ */
+export declare function isHomeEnd(event: KeyboardEvent): boolean;
+/**
+ * Checks if Page Up or Page Down was pressed
+ */
+export declare function isPageUpDown(event: KeyboardEvent): boolean;
+/**
+ * Prevents default behavior for activation keys (Space key scrolling)
+ *
+ * @example
+ * ```svelte
+ * <div
+ *   role="button"
+ *   onkeydown={(e) => {
+ *     keyboard.preventActivation(e);
+ *     if (keyboard.isActivationKey(e)) {
+ *       // Handle activation
+ *     }
+ *   }}
+ * >
+ *   Custom Button
+ * </div>
+ * ```
+ */
+export declare function preventActivation(event: KeyboardEvent): void;
+/**
+ * Gets the direction from an arrow key event
+ */
+export declare function getArrowDirection(event: KeyboardEvent): 'up' | 'down' | 'left' | 'right' | null;
+/**
+ * Keyboard event handler utility object
+ */
+export declare const keyboard: {
+    isActivationKey: typeof isActivationKey;
+    isEscape: typeof isEscape;
+    isArrow: typeof isArrow;
+    isHomeEnd: typeof isHomeEnd;
+    isPageUpDown: typeof isPageUpDown;
+    preventActivation: typeof preventActivation;
+    getArrowDirection: typeof getArrowDirection;
+};

package/dist/utils/a11y/keyboard.js

@@ -0,0 +1,101 @@
+/**
+ * Keyboard event utilities for accessibility
+ */
+/**
+ * Checks if Enter or Space was pressed (for button-like behavior)
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { keyboard } from 'alus-ui';
+ *
+ *   function handleKeydown(e: KeyboardEvent) {
+ *     if (keyboard.isActivationKey(e)) {
+ *       // Activate button
+ *     }
+ *   }
+ * </script>
+ * ```
+ */
+export function isActivationKey(event) {
+    return event.key === 'Enter' || event.key === ' ' || event.key === 'Spacebar';
+}
+/**
+ * Checks if Escape was pressed
+ */
+export function isEscape(event) {
+    return event.key === 'Escape';
+}
+/**
+ * Checks if Arrow key was pressed
+ */
+export function isArrow(event) {
+    return (event.key === 'ArrowUp' ||
+        event.key === 'ArrowDown' ||
+        event.key === 'ArrowLeft' ||
+        event.key === 'ArrowRight');
+}
+/**
+ * Checks if Home or End was pressed
+ */
+export function isHomeEnd(event) {
+    return event.key === 'Home' || event.key === 'End';
+}
+/**
+ * Checks if Page Up or Page Down was pressed
+ */
+export function isPageUpDown(event) {
+    return event.key === 'PageUp' || event.key === 'PageDown';
+}
+/**
+ * Prevents default behavior for activation keys (Space key scrolling)
+ *
+ * @example
+ * ```svelte
+ * <div
+ *   role="button"
+ *   onkeydown={(e) => {
+ *     keyboard.preventActivation(e);
+ *     if (keyboard.isActivationKey(e)) {
+ *       // Handle activation
+ *     }
+ *   }}
+ * >
+ *   Custom Button
+ * </div>
+ * ```
+ */
+export function preventActivation(event) {
+    if (event.key === ' ' || event.key === 'Spacebar') {
+        event.preventDefault();
+    }
+}
+/**
+ * Gets the direction from an arrow key event
+ */
+export function getArrowDirection(event) {
+    switch (event.key) {
+        case 'ArrowUp':
+            return 'up';
+        case 'ArrowDown':
+            return 'down';
+        case 'ArrowLeft':
+            return 'left';
+        case 'ArrowRight':
+            return 'right';
+        default:
+            return null;
+    }
+}
+/**
+ * Keyboard event handler utility object
+ */
+export const keyboard = {
+    isActivationKey,
+    isEscape,
+    isArrow,
+    isHomeEnd,
+    isPageUpDown,
+    preventActivation,
+    getArrowDirection
+};

package/dist/utils/form/README.md

@@ -0,0 +1,164 @@
+# Form Utilities
+
+Reusable utilities for form field management and accessibility.
+
+## Modules
+
+### `ids.ts` - ID Generation
+
+Generate consistent, accessible IDs for form fields.
+
+```typescript
+import { createFieldIds, createFieldGroupIds } from 'alus-ui/utils/form';
+
+const ids = createFieldIds('email');
+// { label: 'alus-ui-email-abc123-label', input: 'alus-ui-email-abc123-input', ... }
+
+const groupIds = createFieldGroupIds('password');
+// { group: 'alus-ui-password-abc123-group', label: 'alus-ui-password-abc123-label', ... }
+```
+
+### `aria.ts` - ARIA Attributes
+
+Build proper ARIA attributes for form fields.
+
+```typescript
+import { getFieldAriaAttrs, hasError, getErrorMessage } from 'alus-ui/utils/form';
+
+const aria = getFieldAriaAttrs({
+	descriptionId: 'help-text',
+	errorId: 'error-message',
+	invalid: true
+});
+// { 'aria-describedby': 'help-text error-message', 'aria-invalid': true }
+
+hasError('Some error'); // true
+getErrorMessage('Some error'); // 'Some error'
+```
+
+### `state.ts` - Form State Management
+
+Create reactive form field and form state.
+
+```typescript
+import { createFormField, createFormState, hasFormErrors, isFormValid } from 'alus-ui/utils/form';
+
+// Single field
+let email = createFormField('');
+// { value: '', error: undefined, touched: false, dirty: false }
+
+// Multiple fields (form)
+let form = createFormState({
+	email: '',
+	password: '',
+	terms: false
+});
+// { values: {...}, errors: {...}, touched: {...}, dirty: {...} }
+
+hasFormErrors(form); // true if any errors
+isFormValid(form); // true if valid and all touched
+```
+
+## Usage Examples
+
+### Form Field with Accessibility
+
+```svelte
+<script lang="ts">
+	import { Input } from 'alus-ui';
+	import { createFieldIds } from 'alus-ui/utils/form';
+
+	const ids = createFieldIds('email');
+
+	let email = $state('');
+	let emailError = $state(undefined);
+	let emailTouched = $state(false);
+</script>
+
+<label for={ids.label}>Email Address</label>
+<Input
+	id={ids.input}
+	bind:value={email}
+	aria-describedby={ids.description}
+	aria-invalid={emailError !== undefined}
+	onblur={() => (emailTouched = true)}
+/>
+<p id={ids.description}>We'll never share your email</p>
+
+{#if emailError && emailTouched}
+	<p id={ids.error} class="error" role="alert">
+		{emailError}
+	</p>
+{/if}
+```
+
+### Form State Manager
+
+```svelte
+<script lang="ts">
+	import { Input, Checkbox } from 'alus-ui';
+	import { createFormState, isFormValid, hasFormErrors } from 'alus-ui/utils/form';
+
+	let form = createFormState({
+		email: '',
+		password: '',
+		terms: false
+	});
+
+	function handleSubmit() {
+		if (isFormValid(form)) {
+			// Submit form
+		}
+	}
+</script>
+
+<Input bind:value={form.values.email} />
+<Input bind:value={form.values.password} />
+<Checkbox bind:checked={form.values.terms as boolean} />
+
+<button disabled={!isFormValid(form)}>Submit</button>
+```
+
+## API Reference
+
+### Functions
+
+#### `createFieldIds(fieldName: string): FieldIds`
+
+Generate IDs for a single form field.
+
+#### `createFieldGroupIds(groupName: string): FieldIds & { group: string }`
+
+Generate IDs for a field group (with group ID).
+
+#### `getFieldAriaAttrs(props: FieldProps): Record<string, string | boolean>`
+
+Generate ARIA attributes for a form field.
+
+#### `hasError(error?: string | boolean): boolean`
+
+Check if a field has an error.
+
+#### `getErrorMessage(error?: string | boolean): string | undefined`
+
+Extract error message from error value.
+
+#### `createFormField<T>(initialValue: T): FormFieldState<T>`
+
+Create state for a single form field.
+
+#### `createFormState<T>(initialValues: T): FormState<T>`
+
+Create state for an entire form.
+
+#### `hasFormErrors(form: FormState): boolean`
+
+Check if form has any errors.
+
+#### `isFormValid(form: FormState): boolean`
+
+Check if form is valid (no errors, all touched).
+
+#### `resetForm(form: FormState, initialValues: T): void`
+
+Reset form to initial state.

package/dist/utils/form/aria.d.ts

@@ -0,0 +1,63 @@
+/**
+ * ARIA attribute utilities for form fields
+ * @module form/aria
+ */
+/**
+ * Props for a form field with label and error states
+ */
+export interface FieldProps {
+    id?: string;
+    label?: string;
+    description?: string;
+    descriptionId?: string;
+    error?: string;
+    errorId?: string;
+    required?: boolean;
+    invalid?: boolean;
+}
+/**
+ * Generate ARIA attributes for a form field based on its state
+ * @param props - Field properties
+ * @returns ARIA attributes object
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getFieldAriaAttrs } from 'alus-ui/utils/form';
+ *
+ *   const aria = getFieldAriaAttrs({
+ *     descriptionId: 'help-id',
+ *     errorId: 'error-id',
+ *     invalid: true
+ *   });
+ * </script>
+ *
+ * <Input {...aria} />
+ * ```
+ */
+export declare function getFieldAriaAttrs(props: FieldProps): Record<string, string>;
+/**
+ * Check if a field has an error state
+ * @param error - Error message or boolean
+ * @returns Whether the field is invalid
+ */
+export declare function hasError(error?: string | boolean): boolean;
+/**
+ * Get the error message to display
+ * @param error - Error message or boolean
+ * @returns Error string or undefined
+ */
+export declare function getErrorMessage(error?: string | boolean): string | undefined;
+/**
+ * Common ARIA roles for form feedback
+ */
+export declare const fieldRoles: {
+    /** Role for an alert message */
+    readonly alert: "alert";
+    /** Role for status information */
+    readonly status: "status";
+};
+/**
+ * Type for ARIA field roles
+ */
+export type FieldRole = (typeof fieldRoles)[keyof typeof fieldRoles];

package/dist/utils/form/aria.js

@@ -0,0 +1,75 @@
+/**
+ * ARIA attribute utilities for form fields
+ * @module form/aria
+ */
+import { buildAriaAttrs } from '../a11y/aria.js';
+/**
+ * Build aria-describedby value from description and error IDs
+ * @param descriptionId - Description element ID
+ * @param errorId - Error element ID
+ * @returns Space-separated IDs for aria-describedby
+ */
+function buildDescribedBy(descriptionId, errorId) {
+    const ids = [];
+    if (descriptionId)
+        ids.push(descriptionId);
+    if (errorId)
+        ids.push(errorId);
+    return ids.length > 0 ? ids.join(' ') : undefined;
+}
+/**
+ * Generate ARIA attributes for a form field based on its state
+ * @param props - Field properties
+ * @returns ARIA attributes object
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { getFieldAriaAttrs } from 'alus-ui/utils/form';
+ *
+ *   const aria = getFieldAriaAttrs({
+ *     descriptionId: 'help-id',
+ *     errorId: 'error-id',
+ *     invalid: true
+ *   });
+ * </script>
+ *
+ * <Input {...aria} />
+ * ```
+ */
+export function getFieldAriaAttrs(props) {
+    return buildAriaAttrs({
+        'aria-label': props.label,
+        'aria-describedby': buildDescribedBy(props.descriptionId || props.description, props.errorId || props.error),
+        'aria-invalid': props.invalid || hasError(props.error),
+        'aria-required': props.required
+    });
+}
+/**
+ * Check if a field has an error state
+ * @param error - Error message or boolean
+ * @returns Whether the field is invalid
+ */
+export function hasError(error) {
+    return error === true || (typeof error === 'string' && error.length > 0);
+}
+/**
+ * Get the error message to display
+ * @param error - Error message or boolean
+ * @returns Error string or undefined
+ */
+export function getErrorMessage(error) {
+    if (typeof error === 'string') {
+        return error || undefined;
+    }
+    return undefined;
+}
+/**
+ * Common ARIA roles for form feedback
+ */
+export const fieldRoles = {
+    /** Role for an alert message */
+    alert: 'alert',
+    /** Role for status information */
+    status: 'status'
+};