alus-ui 0.1.0

package/dist/types/index.js

@@ -0,0 +1,89 @@
+/**
+ * Centralized TypeScript types for accessibility and form attributes
+ * No more magic strings or numbers!
+ */
+/**
+ * Utility constants for common values
+ */
+export const CONSTANTS = {
+    /** Default autocomplete values for common form fields */
+    AUTOCOMPLETE: {
+        EMAIL: 'email',
+        USERNAME: 'username',
+        PASSWORD: 'current-password',
+        NEW_PASSWORD: 'new-password',
+        NAME: 'name',
+        FIRST_NAME: 'given-name',
+        LAST_NAME: 'family-name',
+        PHONE: 'tel',
+        POSTAL_CODE: 'postal-code'
+    },
+    /** Common button types */
+    BUTTON_TYPE: {
+        BUTTON: 'button',
+        SUBMIT: 'submit',
+        RESET: 'reset'
+    },
+    /** Common input types */
+    INPUT_TYPE: {
+        TEXT: 'text',
+        EMAIL: 'email',
+        PASSWORD: 'password',
+        NUMBER: 'number',
+        TEL: 'tel',
+        URL: 'url',
+        SEARCH: 'search'
+    },
+    /** Common input modes */
+    INPUT_MODE: {
+        NONE: 'none',
+        TEXT: 'text',
+        TEL: 'tel',
+        URL: 'url',
+        EMAIL: 'email',
+        NUMERIC: 'numeric',
+        DECIMAL: 'decimal',
+        SEARCH: 'search'
+    },
+    /** Form encoding types */
+    FORM_ENCTYPE: {
+        URLENCODED: 'application/x-www-form-urlencoded',
+        MULTIPART: 'multipart/form-data',
+        TEXT: 'text/plain'
+    },
+    /** Form method types */
+    FORM_METHOD: {
+        POST: 'post',
+        GET: 'get',
+        DIALOG: 'dialog'
+    },
+    /** Form target types */
+    FORM_TARGET: {
+        BLANK: '_blank',
+        SELF: '_self',
+        PARENT: '_parent',
+        TOP: '_top'
+    },
+    /** ARIA live values */
+    ARIA_LIVE: {
+        POLITE: 'polite',
+        ASSERTIVE: 'assertive',
+        OFF: 'off'
+    },
+    /** ARIA orientation values */
+    ARIA_ORIENTATION: {
+        HORIZONTAL: 'horizontal',
+        VERTICAL: 'vertical'
+    },
+    /** ARIA boolean values */
+    ARIA_BOOLEAN: {
+        TRUE: 'true',
+        FALSE: 'false'
+    },
+    /** ARIA tristate values */
+    ARIA_TRISTATE: {
+        TRUE: 'true',
+        FALSE: 'false',
+        MIXED: 'mixed'
+    }
+};

package/dist/utils/a11y/README.md

@@ -0,0 +1,312 @@
+# Accessibility Utilities
+
+Reusable accessibility utilities for WCAG compliance and ARIA attributes.
+
+## Installation
+
+```ts
+import {
+	labelAttrs,
+	validationAttrs,
+	interactiveStateAttrs,
+	widgetAttrs,
+	mergeAttrs
+} from 'alus-ui/a11y';
+```
+
+## ARIA Attribute Builders
+
+### `labelAttrs(options)`
+
+Creates ARIA attributes for labeling and describing elements.
+
+```svelte
+<script>
+	import { Input, labelAttrs } from 'alus-ui';
+</script>
+
+<!-- Using aria-label -->
+<Input {...labelAttrs({ label: 'Email address' })} />
+
+<!-- Using aria-labelledby -->
+<Input id="email" {...labelAttrs({ labelledby: 'email-label' })} />
+<label id="email-label" for="email">Email</label>
+
+<!-- Using aria-describedby -->
+<Input
+	{...labelAttrs({
+		label: 'Password',
+		describedby: 'password-help'
+	})}
+/>
+<p id="password-help">Must be at least 8 characters</p>
+```
+
+### `validationAttrs(options)`
+
+Creates ARIA attributes for form validation states.
+
+```svelte
+<script>
+	import { Input, validationAttrs } from 'alus-ui';
+	let email = $state('');
+	let error = $state('');
+</script>
+
+<Input
+	bind:value={email}
+	{...validationAttrs({
+		invalid: !!error,
+		errormessage: 'email-error'
+	})}
+/>
+{#if error}
+	<p id="email-error" role="alert">{error}</p>
+{/if}
+```
+
+### `interactiveStateAttrs(options)`
+
+Creates ARIA attributes for interactive element states.
+
+```svelte
+<script>
+	import { Button, interactiveStateAttrs } from 'alus-ui';
+	let pressed = $state(false);
+	let expanded = $state(false);
+</script>
+
+<!-- Toggle button -->
+<Button onclick={() => (pressed = !pressed)} {...interactiveStateAttrs({ pressed })}>Toggle</Button>
+
+<!-- Expandable button -->
+<Button onclick={() => (expanded = !expanded)} {...interactiveStateAttrs({ expanded })}>
+	{expanded ? 'Collapse' : 'Expand'}
+</Button>
+```
+
+### `widgetAttrs(options)`
+
+Creates ARIA attributes for complex widgets and roles.
+
+```svelte
+<script>
+	import { widgetAttrs } from 'alus-ui';
+	let value = $state(50);
+</script>
+
+<div
+	role="slider"
+	{...widgetAttrs({
+		valuenow: value,
+		valuemin: 0,
+		valuemax: 100
+	})}
+>
+	Slider
+</div>
+```
+
+### `mergeAttrs(...attrSets)`
+
+Combines multiple ARIA attribute objects into one.
+
+```svelte
+<script>
+	import { mergeAttrs, labelAttrs, interactiveStateAttrs } from 'alus-ui';
+</script>
+
+<button {...mergeAttrs(labelAttrs({ label: 'Menu' }), interactiveStateAttrs({ expanded: true }))}>
+	Menu
+</button>
+```
+
+## Focus Management
+
+```ts
+import { focus } from 'alus-ui/a11y';
+
+// Trap focus within a container (for modals, dropdowns)
+const cleanup = focus.trap(modalElement);
+// Call cleanup() when modal closes
+
+// Focus first element
+focus.focusFirst(dialogElement);
+
+// Focus last element
+focus.focusLast(dialogElement);
+
+// Check if element is focusable
+if (focus.isFocusable(element)) {
+	element.focus();
+}
+```
+
+## Keyboard Utilities
+
+```ts
+import { keyboard } from 'alus-ui/a11y';
+
+element.addEventListener('keydown', (e) => {
+	// Check for activation keys (Enter/Space)
+	if (keyboard.isActivationKey(e)) {
+		// Activate button
+	}
+
+	// Check for Escape
+	if (keyboard.isEscape(e)) {
+		// Close modal/menu
+	}
+
+	// Check for arrow keys
+	if (keyboard.isArrow(e)) {
+		const direction = keyboard.getArrowDirection(e);
+		// Handle arrow navigation
+	}
+
+	// Prevent default Space key scrolling
+	keyboard.preventActivation(e);
+});
+```
+
+## ID Generation
+
+```svelte
+<script>
+	import { generateId } from 'alus-ui/a11y';
+
+	const labelId = generateId('label');
+	const errorId = generateId('error');
+	const descriptionId = generateId('desc');
+</script>
+
+<Input
+	{...labelAttrs({
+		labelledby: labelId,
+		describedby: descriptionId
+	})}
+	{...validationAttrs({ errormessage: errorId })}
+/>
+<label id={labelId}>Email</label>
+<p id={descriptionId}>Enter your email address</p>
+<p id={errorId} role="alert">Invalid email format</p>
+```
+
+## Examples
+
+### Accessible Form Field
+
+```svelte
+<script>
+	import { Input, labelAttrs, validationAttrs, generateId } from 'alus-ui';
+
+	let value = $state('');
+	let error = $state('');
+
+	const labelId = generateId('label');
+	const errorId = generateId('error');
+	const helpId = generateId('help');
+</script>
+
+<div class="form-field">
+	<label id={labelId} for="email">Email Address</label>
+
+	<Input
+		id="email"
+		bind:value
+		placeholder="you@example.com"
+		{...labelAttrs({
+			labelledby: labelId,
+			describedby: `${helpId} ${errorId}`
+		})}
+		{...validationAttrs({
+			invalid: !!error,
+			required: true,
+			errormessage: errorId
+		})}
+		required
+		autocomplete="email"
+		inputmode="email"
+	/>
+
+	<p id={helpId} class="help-text">We'll never share your email with anyone else.</p>
+
+	{#if error}
+		<p id={errorId} class="error" role="alert" aria-live="polite">
+			{error}
+		</p>
+	{/if}
+</div>
+```
+
+### Accessible Toggle Button
+
+```svelte
+<script>
+	import { Button, interactiveStateAttrs } from 'alus-ui';
+
+	let isPressed = $state(false);
+</script>
+
+<Button
+	onclick={() => (isPressed = !isPressed)}
+	aria-label="Toggle mute"
+	{...interactiveStateAttrs({ pressed: isPressed })}
+>
+	{#if isPressed}
+		Muted
+	{:else}
+		Unmuted
+	{/if}
+</Button>
+```
+
+### Accessible Dropdown Menu
+
+```svelte
+<script>
+	import {
+		Button,
+		widgetAttrs,
+		labelAttrs,
+		interactiveStateAttrs,
+		mergeAttrs,
+		generateId
+	} from 'alus-ui';
+
+	let isOpen = $state(false);
+	const menuId = generateId('menu');
+</script>
+
+<div class="dropdown">
+	<Button
+		{...mergeAttrs(
+			labelAttrs({ label: 'Options menu' }),
+			interactiveStateAttrs({ expanded: isOpen }),
+			widgetAttrs({
+				haspopup: 'menu',
+				controls: menuId
+			})
+		)}
+		onclick={() => (isOpen = !isOpen)}
+	>
+		Options
+	</Button>
+
+	{#if isOpen}
+		<ul id={menuId} role="menu">
+			<li role="menuitem">Option 1</li>
+			<li role="menuitem">Option 2</li>
+			<li role="menuitem">Option 3</li>
+		</ul>
+	{/if}
+</div>
+```
+
+## Benefits
+
+(^_^) **DRY**: Don't repeat ARIA logic across components
+(^_^) **Type-safe**: Full TypeScript support with proper types
+(^_^) **Composable**: Mix and match utilities for complex patterns
+(^_^) **Tested**: Follows WCAG 2.1 AA standards
+(^\_^) **Maintainable**: Centralized accessibility logic

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

@@ -0,0 +1,88 @@
+/**
+ * ARIA attribute utilities for WCAG compliance
+ */
+import type { LabelConfig, ValidationConfig, InteractiveStateConfig, WidgetConfig } from '../../types/index.js';
+/**
+ * Builds ARIA attributes object from a partial record, filtering out undefined values
+ * and converting boolean/number/undefined values to strings for HTML attributes
+ *
+ * @example
+ * ```ts
+ * const attrs = buildAriaAttrs({
+ *   'aria-label': 'Close',
+ *   'aria-expanded': false,
+ *   'aria-valuenow': 50,
+ *   'aria-hidden': undefined
+ * });
+ * // { 'aria-label': 'Close', 'aria-expanded': 'false', 'aria-valuenow': '50' }
+ * ```
+ */
+export declare function buildAriaAttrs(attrs: Record<string, string | number | boolean | undefined>): Record<string, string>;
+/**
+ * Creates ARIA attributes for labeling and describing elements
+ *
+ * @example
+ * ```svelte
+ * <Input
+ *   id="email"
+ *   {...labelAttrs({ label: 'Email address' })}
+ * />
+ * ```
+ */
+export declare function labelAttrs(options?: LabelConfig): Record<string, string>;
+/**
+ * Creates ARIA attributes for form validation states
+ *
+ * @example
+ * ```svelte
+ * <Input
+ *   bind:value={email}
+ *   {...validationAttrs({ invalid: !isValid, errormessage: 'email-error' })}
+ * />
+ * <p id="email-error" role="alert">{error}</p>
+ * ```
+ */
+export declare function validationAttrs(options?: ValidationConfig): Record<string, string>;
+/**
+ * Creates ARIA attributes for interactive element states
+ *
+ * @example
+ * ```svelte
+ * <Button
+ *   onclick={() => pressed = !pressed}
+ *   {...interactiveStateAttrs({ pressed })}
+ * >
+ *   Toggle
+ * </Button>
+ * ```
+ */
+export declare function interactiveStateAttrs(options?: InteractiveStateConfig): Record<string, string>;
+/**
+ * Creates ARIA attributes for complex widgets and roles
+ *
+ * @example
+ * ```svelte
+ * <div role="slider" {...widgetAttrs({
+ *   valuenow: value,
+ *   valuemin: 0,
+ *   valuemax: 100
+ * })} />
+ * ```
+ */
+export declare function widgetAttrs(options?: WidgetConfig): Record<string, string>;
+/**
+ * Combines multiple ARIA attribute objects into one
+ * Useful for composing different accessibility patterns
+ *
+ * @example
+ * ```svelte
+ * <button {...mergeAttrs(
+ *   labelAttrs({ label: 'Menu' }),
+ *   interactiveStateAttrs({ expanded: isOpen }),
+ *   widgetAttrs({ haspopup: 'menu', controls: 'menu-id' })
+ * )}>
+ *   Menu
+ * </button>
+ * ```
+ */
+export declare function mergeAttrs(...attrSets: Record<string, string>[]): Record<string, string>;

package/dist/utils/a11y/aria.js

@@ -0,0 +1,131 @@
+/**
+ * Builds ARIA attributes object from a partial record, filtering out undefined values
+ * and converting boolean/number/undefined values to strings for HTML attributes
+ *
+ * @example
+ * ```ts
+ * const attrs = buildAriaAttrs({
+ *   'aria-label': 'Close',
+ *   'aria-expanded': false,
+ *   'aria-valuenow': 50,
+ *   'aria-hidden': undefined
+ * });
+ * // { 'aria-label': 'Close', 'aria-expanded': 'false', 'aria-valuenow': '50' }
+ * ```
+ */
+export function buildAriaAttrs(attrs) {
+    const result = {};
+    for (const [key, value] of Object.entries(attrs)) {
+        if (value !== undefined) {
+            result[key] = String(value);
+        }
+    }
+    return result;
+}
+/**
+ * Creates ARIA attributes for labeling and describing elements
+ *
+ * @example
+ * ```svelte
+ * <Input
+ *   id="email"
+ *   {...labelAttrs({ label: 'Email address' })}
+ * />
+ * ```
+ */
+export function labelAttrs(options = {}) {
+    return buildAriaAttrs({
+        'aria-label': options.label,
+        'aria-labelledby': options.labelledby,
+        'aria-describedby': options.describedby
+    });
+}
+/**
+ * Creates ARIA attributes for form validation states
+ *
+ * @example
+ * ```svelte
+ * <Input
+ *   bind:value={email}
+ *   {...validationAttrs({ invalid: !isValid, errormessage: 'email-error' })}
+ * />
+ * <p id="email-error" role="alert">{error}</p>
+ * ```
+ */
+export function validationAttrs(options = {}) {
+    return buildAriaAttrs({
+        'aria-invalid': options.invalid,
+        'aria-required': options.required,
+        'aria-errormessage': options.errormessage
+    });
+}
+/**
+ * Creates ARIA attributes for interactive element states
+ *
+ * @example
+ * ```svelte
+ * <Button
+ *   onclick={() => pressed = !pressed}
+ *   {...interactiveStateAttrs({ pressed })}
+ * >
+ *   Toggle
+ * </Button>
+ * ```
+ */
+export function interactiveStateAttrs(options = {}) {
+    return buildAriaAttrs({
+        'aria-pressed': options.pressed,
+        'aria-expanded': options.expanded,
+        'aria-checked': options.checked,
+        'aria-selected': options.selected,
+        'aria-disabled': options.disabled,
+        'aria-busy': options.busy,
+        'aria-current': options.current
+    });
+}
+/**
+ * Creates ARIA attributes for complex widgets and roles
+ *
+ * @example
+ * ```svelte
+ * <div role="slider" {...widgetAttrs({
+ *   valuenow: value,
+ *   valuemin: 0,
+ *   valuemax: 100
+ * })} />
+ * ```
+ */
+export function widgetAttrs(options = {}) {
+    return buildAriaAttrs({
+        'aria-controls': options.controls,
+        'aria-haspopup': options.haspopup,
+        'aria-valuenow': options.valuenow,
+        'aria-valuetext': options.valuetext,
+        'aria-valuemin': options.valuemin,
+        'aria-valuemax': options.valuemax,
+        'aria-live': options.live,
+        'aria-activedescendant': options.activedescendant,
+        'aria-posinset': options.posinset,
+        'aria-setsize': options.setsize,
+        'aria-level': options.level,
+        'aria-orientation': options.orientation
+    });
+}
+/**
+ * Combines multiple ARIA attribute objects into one
+ * Useful for composing different accessibility patterns
+ *
+ * @example
+ * ```svelte
+ * <button {...mergeAttrs(
+ *   labelAttrs({ label: 'Menu' }),
+ *   interactiveStateAttrs({ expanded: isOpen }),
+ *   widgetAttrs({ haspopup: 'menu', controls: 'menu-id' })
+ * )}>
+ *   Menu
+ * </button>
+ * ```
+ */
+export function mergeAttrs(...attrSets) {
+    return Object.assign({}, ...attrSets);
+}

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

@@ -0,0 +1,51 @@
+/**
+ * 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 declare function trap(container: HTMLElement): () => void;
+/**
+ * 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 declare function focusFirst(container: HTMLElement): void;
+/**
+ * Moves focus to last focusable element in container
+ */
+export declare function focusLast(container: HTMLElement): void;
+/**
+ * Checks if an element can receive focus
+ */
+export declare function isFocusable(element: HTMLElement): boolean;