alus-ui 0.1.0

package/dist/components/utility/visually-hidden/VisuallyHidden.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+	import type { AriaLive, AriaRelevant } from '../../../types/index.js';
+
+	interface Props {
+		children?: import('svelte').Snippet;
+		as?: 'span' | 'div';
+		role?: string;
+		'aria-live'?: AriaLive;
+		'aria-atomic'?: boolean | 'true' | 'false';
+		'aria-relevant'?: AriaRelevant;
+		'aria-label'?: string;
+	}
+
+	let {
+		children,
+		as = 'span',
+		role,
+		'aria-live': ariaLive,
+		'aria-atomic': ariaAtomic,
+		'aria-relevant': ariaRelevant,
+		'aria-label': ariaLabel
+	}: Props = $props();
+
+	const hiddenStyle =
+		'position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;';
+</script>
+
+{#if as === 'div'}
+	<div
+		style={hiddenStyle}
+		{role}
+		aria-live={ariaLive}
+		aria-atomic={ariaAtomic}
+		aria-relevant={ariaRelevant}
+		aria-label={ariaLabel}
+	>
+		{#if children}{@render children()}{/if}
+	</div>
+{:else}
+	<span
+		style={hiddenStyle}
+		{role}
+		aria-live={ariaLive}
+		aria-atomic={ariaAtomic}
+		aria-relevant={ariaRelevant}
+		aria-label={ariaLabel}
+	>
+		{#if children}{@render children()}{/if}
+	</span>
+{/if}

package/dist/components/utility/visually-hidden/VisuallyHidden.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { AriaLive, AriaRelevant } from '../../../types/index.js';
+interface Props {
+    children?: import('svelte').Snippet;
+    as?: 'span' | 'div';
+    role?: string;
+    'aria-live'?: AriaLive;
+    'aria-atomic'?: boolean | 'true' | 'false';
+    'aria-relevant'?: AriaRelevant;
+    'aria-label'?: string;
+}
+declare const VisuallyHidden: import("svelte").Component<Props, {}, "">;
+type VisuallyHidden = ReturnType<typeof VisuallyHidden>;
+export default VisuallyHidden;

package/dist/components/utility/visually-hidden/index.d.ts

@@ -0,0 +1 @@
+export { default as VisuallyHidden } from './VisuallyHidden.svelte';

package/dist/components/utility/visually-hidden/index.js

@@ -0,0 +1 @@
+export { default as VisuallyHidden } from './VisuallyHidden.svelte';

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Alus - Unstyled, accessible Svelte 5 components
+ * @module alus
+ */
+export * from './components/index.js';
+export * from './utils/index.js';
+export * from './types/index.js';

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Alus - Unstyled, accessible Svelte 5 components
+ * @module alus
+ */
+// Export UI components
+export * from './components/index.js';
+// Export utilities (includes accessibility utilities)
+export * from './utils/index.js';
+// Export types
+export * from './types/index.js';

package/dist/types/README.md

@@ -0,0 +1,299 @@
+# Type-safe Usage Examples
+
+## Using Constants Instead of Magic Strings
+
+### (x_x) Before (Magic Strings)
+
+```svelte
+<Button type="button" formenctype="application/x-www-form-urlencoded" formmethod="post" />
+
+<Input type="email" autocomplete="email" inputmode="email" aria-expanded="true" />
+```
+
+### (^\_^) After (Type-safe Constants)
+
+```svelte
+<script>
+	import { Button, Input, CONSTANTS } from 'alus-ui';
+</script>
+
+<Button
+	type={CONSTANTS.BUTTON_TYPE.BUTTON}
+	formenctype={CONSTANTS.FORM_ENCTYPE.URLENCODED}
+	formmethod={CONSTANTS.FORM_METHOD.POST}
+/>
+
+<Input
+	type={CONSTANTS.INPUT_TYPE.EMAIL}
+	autocomplete={CONSTANTS.AUTOCOMPLETE.EMAIL}
+	inputmode={CONSTANTS.INPUT_MODE.EMAIL}
+	aria-expanded={CONSTANTS.ARIA_BOOLEAN.TRUE}
+/>
+```
+
+## Common Form Field Patterns
+
+### Email Field
+
+```svelte
+<script>
+	import { Input, CONSTANTS } from 'alus-ui';
+	import { generateId, labelAttrs } from 'alus-ui/a11y';
+
+	const labelId = generateId('label');
+	let email = $state('');
+</script>
+
+<Input
+	id="email"
+	bind:value={email}
+	type={CONSTANTS.INPUT_TYPE.EMAIL}
+	autocomplete={CONSTANTS.AUTOCOMPLETE.EMAIL}
+	inputmode={CONSTANTS.INPUT_MODE.EMAIL}
+	placeholder="you@example.com"
+	{...labelAttrs({ labelledby: labelId })}
+	required
+/>
+<label id={labelId} for="email">Email Address</label>
+```
+
+### Password Field
+
+```svelte
+<script>
+	import { Input, CONSTANTS } from 'alus-ui';
+	import { generateId, labelAttrs } from 'alus-ui/a11y';
+
+	const labelId = generateId('label');
+	let password = $state('');
+</script>
+
+<Input
+	id="password"
+	bind:value={password}
+	type={CONSTANTS.INPUT_TYPE.PASSWORD}
+	autocomplete={CONSTANTS.AUTOCOMPLETE.NEW_PASSWORD}
+	placeholder="Enter password"
+	{...labelAttrs({ labelledby: labelId })}
+	required
+/>
+<label id={labelId} for="password">Password</label>
+```
+
+### Phone Field
+
+```svelte
+<script>
+	import { Input, CONSTANTS } from 'alus-ui';
+	import { generateId, labelAttrs } from 'alus-ui/a11y';
+
+	const labelId = generateId('label');
+	let phone = $state('');
+</script>
+
+<Input
+	id="phone"
+	bind:value={phone}
+	type={CONSTANTS.INPUT_TYPE.TEL}
+	autocomplete={CONSTANTS.AUTOCOMPLETE.PHONE}
+	inputmode={CONSTANTS.INPUT_MODE.TEL}
+	placeholder="+1 (555) 123-4567"
+	{...labelAttrs({ labelledby: labelId })}
+/>
+<label id={labelId} for="phone">Phone Number</label>
+```
+
+### Name Fields
+
+```svelte
+<script>
+	import { Input, CONSTANTS } from 'alus-ui';
+	import { generateId, labelAttrs } from 'alus-ui/a11y';
+
+	const firstNameId = generateId('label');
+	const lastNameId = generateId('label');
+
+	let firstName = $state('');
+	let lastName = $state('');
+</script>
+
+<div class="name-fields">
+	<div>
+		<Input
+			id="first-name"
+			bind:value={firstName}
+			type={CONSTANTS.INPUT_TYPE.TEXT}
+			autocomplete={CONSTANTS.AUTOCOMPLETE.FIRST_NAME}
+			placeholder="John"
+			{...labelAttrs({ labelledby: firstNameId })}
+		/>
+		<label id={firstNameId} for="first-name">First Name</label>
+	</div>
+
+	<div>
+		<Input
+			id="last-name"
+			bind:value={lastName}
+			type={CONSTANTS.INPUT_TYPE.TEXT}
+			autocomplete={CONSTANTS.AUTOCOMPLETE.LAST_NAME}
+			placeholder="Doe"
+			{...labelAttrs({ labelledby: lastNameId })}
+		/>
+		<label id={lastNameId} for="last-name">Last Name</label>
+	</div>
+</div>
+```
+
+### Submit Button with Form Encoding
+
+```svelte
+<script>
+	import { Button, CONSTANTS } from 'alus-ui';
+</script>
+
+<Button
+	type={CONSTANTS.BUTTON_TYPE.SUBMIT}
+	formenctype={CONSTANTS.FORM_ENCTYPE.MULTIPART}
+	formmethod={CONSTANTS.FORM_METHOD.POST}
+>
+	Upload File
+</Button>
+```
+
+### Toggle Button with ARIA States
+
+```svelte
+<script>
+	import { Button, CONSTANTS } from 'alus-ui';
+	import { interactiveStateAttrs } from 'alus-ui/a11y';
+
+	let isPressed = $state(false);
+</script>
+
+<Button
+	onclick={() => (isPressed = !isPressed)}
+	aria-label="Toggle mute"
+	{...interactiveStateAttrs({ pressed: isPressed })}
+>
+	{#if isPressed}
+		Muted
+	{:else}
+		Unmuted
+	{/if}
+</Button>
+```
+
+### Dropdown Menu Button
+
+```svelte
+<script>
+  import { Button, CONSTANTS, type AriaHaspopup } from 'alus-ui';
+  import { interactiveStateAttrs, widgetAttrs, mergeAttrs } from 'alus-ui/a11y';
+
+  let isOpen = $state(false);
+  const menuId = 'options-menu';
+</script>
+
+<Button
+  aria-label="Options menu"
+  {...mergeAttrs(
+    interactiveStateAttrs({ expanded: isOpen }),
+    widgetAttrs({
+      haspopup: CONSTANTS.ARIA_BOOLEAN.TRUE as AriaHaspopup,
+      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}
+```
+
+### Search Field with Live Results
+
+```svelte
+<script>
+	import { Input, CONSTANTS } from 'alus-ui';
+	import { labelAttrs, widgetAttrs } from 'alus-ui/a11y';
+
+	let searchQuery = $state('');
+	let results = $state([]);
+</script>
+
+<Input
+	id="search"
+	bind:value={searchQuery}
+	type={CONSTANTS.INPUT_TYPE.SEARCH}
+	inputmode={CONSTANTS.INPUT_MODE.SEARCH}
+	placeholder="Search..."
+	{...labelAttrs({ label: 'Search products' })}
+	{...widgetAttrs({
+		live: CONSTANTS.ARIA_LIVE.POLITE,
+		controls: 'search-results'
+	})}
+/>
+
+{#if results.length > 0}
+	<ul id="search-results" role="listbox" aria-label="Search results">
+		{#each results as result}
+			<li role="option">{result.name}</li>
+		{/each}
+	</ul>
+{/if}
+```
+
+## Benefits of Using Constants
+
+(^_^) **Type Safety**: Autocomplete helps you find the right value
+(^_^) **No Typos**: Can't misspell a constant value
+(^_^) **Refactoring**: Change values in one place
+(^_^) **Discoverability**: IDE shows all available options
+(^_^) **Documentation**: Constants serve as inline documentation
+(^_^) **Consistency**: Same values throughout your app
+
+## Exported Types
+
+You can also import and use the types directly:
+
+```ts
+import type {
+	InputType,
+	InputMode,
+	AutocompleteValue,
+	ButtonType,
+	FormEncType,
+	FormMethod,
+	FormTarget,
+	AriaBoolean,
+	AriaTristate,
+	AriaHaspopup,
+	AriaLive,
+	AriaOrientation
+} from 'alus-ui';
+
+// Use in your own components
+function createInput(type: InputType) {
+	return { type };
+}
+```
+
+## Type Exports for Extension
+
+```ts
+import type { FormFieldConfig, LabelConfig, ValidationConfig } from 'alus-ui';
+
+// Extend for your custom components
+interface MyCustomFieldConfig extends FormFieldConfig {
+	customProp: string;
+	labelConfig: LabelConfig;
+	validationConfig: ValidationConfig;
+}
+```

package/dist/types/index.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Centralized TypeScript types for accessibility and form attributes
+ * No more magic strings or numbers!
+ */
+/**
+ * HTML5 autocomplete attribute values
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
+ */
+export type AutocompleteValue = 'off' | 'on' | 'name' | 'honorific-prefix' | 'given-name' | 'additional-name' | 'family-name' | 'honorific-suffix' | 'nickname' | 'email' | 'username' | 'new-password' | 'current-password' | 'one-time-code' | 'organization-title' | 'organization' | 'street-address' | 'address-line1' | 'address-line2' | 'address-line3' | 'address-level4' | 'address-level3' | 'address-level2' | 'address-level1' | 'country' | 'country-name' | 'postal-code' | 'cc-name' | 'cc-given-name' | 'cc-additional-name' | 'cc-family-name' | 'cc-number' | 'cc-exp' | 'cc-exp-month' | 'cc-exp-year' | 'cc-csc' | 'cc-type' | 'transaction-currency' | 'transaction-amount' | 'language' | 'bday' | 'bday-day' | 'bday-month' | 'bday-year' | 'sex' | 'url' | 'photo';
+/**
+ * HTML input types
+ */
+export type InputType = 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'search';
+/**
+ * HTML inputmode attribute values
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode
+ */
+export type InputMode = 'none' | 'text' | 'tel' | 'url' | 'email' | 'numeric' | 'decimal' | 'search';
+/**
+ * HTML button types
+ */
+export type ButtonType = 'button' | 'submit' | 'reset';
+/**
+ * Form encoding types
+ */
+export type FormEncType = 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain';
+/**
+ * Form method types
+ */
+export type FormMethod = 'post' | 'get' | 'dialog';
+/**
+ * Form target types
+ */
+export type FormTarget = '_blank' | '_self' | '_parent' | '_top' | string;
+/** Source of truth for ARIA attribute value types */
+type AriaAttrs = import('svelte/elements').AriaAttributes;
+type AriaAttrValue<K extends keyof AriaAttrs> = NonNullable<AriaAttrs[K]>;
+/** ARIA boolean values (can be string or boolean per ARIA spec) */
+export type AriaBoolean = AriaAttrValue<'aria-expanded'>;
+/** ARIA tristate values (for checkboxes, etc.) */
+export type AriaTristate = AriaAttrValue<'aria-pressed'>;
+/** ARIA haspopup values */
+export type AriaHaspopup = AriaAttrValue<'aria-haspopup'>;
+/** ARIA live region values */
+export type AriaLive = AriaAttrValue<'aria-live'>;
+/** ARIA current values */
+export type AriaCurrent = AriaAttrValue<'aria-current'>;
+/** ARIA relevant tokens */
+export type AriaRelevant = AriaAttrValue<'aria-relevant'>;
+/** ARIA orientation values */
+export type AriaOrientation = AriaAttrValue<'aria-orientation'>;
+/**
+ * Common ID reference type
+ */
+export type IdReference = string;
+/**
+ * Direction type for arrow keys
+ */
+export type Direction = 'up' | 'down' | 'left' | 'right';
+/**
+ * Helper type to normalize ARIA boolean values
+ * Converts string literals to actual booleans
+ */
+export type NormalizedAriaBoolean<T> = T extends 'true' | 'false' ? boolean : T;
+/**
+ * Helper to normalize ARIA tristate values
+ */
+export type NormalizedAriaTristate<T> = T extends 'true' | 'false' | 'mixed' ? boolean | 'mixed' : T;
+/**
+ * Utility constants for common values
+ */
+export declare const CONSTANTS: {
+    /** Default autocomplete values for common form fields */
+    readonly AUTOCOMPLETE: {
+        readonly EMAIL: "email";
+        readonly USERNAME: "username";
+        readonly PASSWORD: "current-password";
+        readonly NEW_PASSWORD: "new-password";
+        readonly NAME: "name";
+        readonly FIRST_NAME: "given-name";
+        readonly LAST_NAME: "family-name";
+        readonly PHONE: "tel";
+        readonly POSTAL_CODE: "postal-code";
+    };
+    /** Common button types */
+    readonly BUTTON_TYPE: {
+        readonly BUTTON: "button";
+        readonly SUBMIT: "submit";
+        readonly RESET: "reset";
+    };
+    /** Common input types */
+    readonly INPUT_TYPE: {
+        readonly TEXT: "text";
+        readonly EMAIL: "email";
+        readonly PASSWORD: "password";
+        readonly NUMBER: "number";
+        readonly TEL: "tel";
+        readonly URL: "url";
+        readonly SEARCH: "search";
+    };
+    /** Common input modes */
+    readonly INPUT_MODE: {
+        readonly NONE: "none";
+        readonly TEXT: "text";
+        readonly TEL: "tel";
+        readonly URL: "url";
+        readonly EMAIL: "email";
+        readonly NUMERIC: "numeric";
+        readonly DECIMAL: "decimal";
+        readonly SEARCH: "search";
+    };
+    /** Form encoding types */
+    readonly FORM_ENCTYPE: {
+        readonly URLENCODED: "application/x-www-form-urlencoded";
+        readonly MULTIPART: "multipart/form-data";
+        readonly TEXT: "text/plain";
+    };
+    /** Form method types */
+    readonly FORM_METHOD: {
+        readonly POST: "post";
+        readonly GET: "get";
+        readonly DIALOG: "dialog";
+    };
+    /** Form target types */
+    readonly FORM_TARGET: {
+        readonly BLANK: "_blank";
+        readonly SELF: "_self";
+        readonly PARENT: "_parent";
+        readonly TOP: "_top";
+    };
+    /** ARIA live values */
+    readonly ARIA_LIVE: {
+        readonly POLITE: "polite";
+        readonly ASSERTIVE: "assertive";
+        readonly OFF: "off";
+    };
+    /** ARIA orientation values */
+    readonly ARIA_ORIENTATION: {
+        readonly HORIZONTAL: "horizontal";
+        readonly VERTICAL: "vertical";
+    };
+    /** ARIA boolean values */
+    readonly ARIA_BOOLEAN: {
+        readonly TRUE: "true";
+        readonly FALSE: "false";
+    };
+    /** ARIA tristate values */
+    readonly ARIA_TRISTATE: {
+        readonly TRUE: "true";
+        readonly FALSE: "false";
+        readonly MIXED: "mixed";
+    };
+};
+/**
+ * Type helper to extract values from constants object
+ */
+export type ConstValue<T> = T extends {
+    [K: string]: infer V;
+} ? V : never;
+/**
+ * Common form field configuration types
+ */
+export interface FormFieldConfig {
+    /** Field identifier */
+    id?: string;
+    /** Field name for form submission */
+    name?: string;
+    /** Whether the field is required */
+    required?: boolean;
+    /** Whether the field is disabled */
+    disabled?: boolean;
+    /** Whether the field is read-only */
+    readonly?: boolean;
+    /** Field label */
+    label?: string;
+    /** Field description/help text */
+    description?: string;
+    /** Error message */
+    error?: string;
+}
+/**
+ * Accessible label configuration
+ */
+export interface LabelConfig {
+    /** Direct label for screen readers */
+    label?: string;
+    /** ID of element that labels this component */
+    labelledby?: string;
+    /** ID of element that describes this component */
+    describedby?: string;
+}
+/**
+ * Validation state configuration
+ */
+export interface ValidationConfig {
+    /** Whether the value is invalid */
+    invalid?: boolean;
+    /** Whether the field is required */
+    required?: boolean;
+    /** ID of element containing error message */
+    errormessage?: string;
+}
+/**
+ * Interactive state configuration
+ */
+export interface InteractiveStateConfig {
+    /** Toggle button pressed state */
+    pressed?: boolean | 'mixed';
+    /** Expanded/collapsed state */
+    expanded?: boolean;
+    /** Checkbox/switch checked state */
+    checked?: boolean | 'mixed';
+    /** Listbox/tab/option selected state */
+    selected?: AriaBoolean;
+    /** Disabled state */
+    disabled?: boolean;
+    /** Busy/loading state */
+    busy?: boolean;
+    /** Current item within container (nav/breadcrumb/stepper) */
+    current?: AriaCurrent;
+}
+/**
+ * Widget-specific configuration
+ */
+export interface WidgetConfig {
+    /** Element that this controls */
+    controls?: string;
+    /** Popup behavior */
+    haspopup?: AriaHaspopup;
+    /** Current value within a range */
+    valuenow?: number;
+    /** Text representation of value */
+    valuetext?: string;
+    /** Minimum value */
+    valuemin?: number;
+    /** Maximum value */
+    valuemax?: number;
+    /** Live region behavior */
+    live?: AriaLive;
+    /** Element ID that receives focus */
+    activedescendant?: string;
+    /** Current position in a list */
+    posinset?: number;
+    /** Total items in a list */
+    setsize?: number;
+    /** Heading level */
+    level?: number;
+    /** Orientation */
+    orientation?: AriaOrientation;
+}
+export {};