alus-ui 0.1.0

package/README.md

@@ -0,0 +1,289 @@
+# alus-ui
+
+> **Unstyled, accessible Svelte 5 components** with full keyboard navigation and WCAG 2.1 AA compliance
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Svelte 5](https://img.shields.io/badge/Svelte-5.55-orange)](https://svelte.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
+[![npm package](https://img.shields.io/badge/npm-alus--ui-critical)](https://www.npmjs.com/package/alus-ui)
+
+alus-ui provides a set of primitive UI components that are:
+
+- **Unstyled** - Complete styling freedom with Tailwind CSS or any CSS framework
+- **Accessible** - WCAG 2.1 AA compliant with proper ARIA attributes
+- **Keyboard-friendly** - Full keyboard navigation support
+- **Type-safe** - Built with TypeScript
+- **Svelte 5 Native** - Uses runes mode (`$props`, `$derived`, `$state`)
+
+## Installation
+
+```bash
+npm install alus-ui
+# or
+pnpm add alus-ui
+# or
+yarn add alus-ui
+```
+
+## Quick Start
+
+```svelte
+<script lang="ts">
+	import { Button, Input } from 'alus-ui';
+
+	let name = $state('');
+</script>
+
+<Input bind:value={name} placeholder="Enter your name" aria-label="Name input" />
+
+<Button onclick={() => alert(`Hello ${name}!`)}>Submit</Button>
+```
+
+## Available Components
+
+### Form Components (^\_^)b
+
+- **Button** - Accessible button with ARIA support and toggle states
+- **Input** - Text input with validation, error states, and accessibility
+
+## Features
+
+### (°_°) Accessibility First
+
+- WCAG 2.1 AA compliant out of the box
+- Proper ARIA attributes (aria-label, aria-describedby, aria-invalid, etc.)
+- Screen reader support with semantic HTML
+- Keyboard navigation with visible focus indicators
+- Live regions for dynamic content announcements
+
+### (☆^\_☆) Complete Styling Control
+
+- No default styles or colors
+- Works seamlessly with Tailwind CSS
+- Easy to theme with CSS variables
+- Responsive and mobile-friendly
+
+### (☆^O^☆) Svelte 5 Runes Mode
+
+- Modern reactive syntax with `$props`, `$derived`, `$state`
+- Better TypeScript support
+- Improved performance
+- Future-proof Svelte architecture
+
+### (^\_^) Type Safety
+
+- Full TypeScript support
+- Type-safe props and events
+- IntelliSense in IDEs
+
+## Styling with Tailwind CSS
+
+```svelte
+<script lang="ts">
+	import { Button } from 'alus-ui';
+</script>
+
+<Button class="rounded bg-blue-600 px-4 py-2 text-white hover:bg-blue-700" aria-label="Submit form">
+	Submit
+</Button>
+```
+
+## Form Validation Example
+
+```svelte
+<script lang="ts">
+	import { Input } from 'alus-ui';
+
+	let email = $state('');
+	let emailError = $derived.by(() => {
+		if (email && !email.includes('@')) {
+			return 'Please enter a valid email';
+		}
+		return '';
+	});
+</script>
+
+<label for="email">Email</label>
+<Input
+	id="email"
+	name="email"
+	type="email"
+	bind:value={email}
+	aria-invalid={!!emailError}
+	aria-describedby={emailError ? 'email-error' : undefined}
+	class={emailError ? 'border-red-500' : 'border-gray-300'}
+/>
+{#if emailError}
+	<p id="email-error" class="text-red-500" role="alert">
+		{emailError}
+	</p>
+{/if}
+```
+
+## Component API
+
+### Button
+
+```svelte
+<Button type="button" disabled={false} aria-pressed={undefined} class="" onclick={() => {}}>
+	Button content
+</Button>
+```
+
+**Props:**
+
+- `type?: 'button' | 'submit' | 'reset'` - Button type (default: 'button')
+- `disabled?: boolean` - Disabled state
+- `aria-pressed?: boolean` - Toggle button state
+- `class?: string` - CSS classes for styling
+- All standard HTML button attributes
+
+### Input
+
+```svelte
+<Input
+	type="text"
+	value={''}
+	autocomplete="off"
+	inputmode="text"
+	aria-invalid={false}
+	aria-label={undefined}
+	aria-describedby={undefined}
+	class=""
+	oninput={(e) => {}}
+/>
+```
+
+**Props:**
+
+- `type?: HTMLInputTypeAttribute` - Input type (default: 'text')
+- `value?: string` - Input value (use `bind:value` for two-way binding)
+- `autocomplete?: string` - Autocomplete attribute
+- `inputmode?: string` - Input mode for mobile keyboards
+- `aria-invalid?: boolean` - Invalid state for validation
+- `aria-label?: string` - Accessibility label
+- `aria-describedby?: string` - ID of describing element
+- `class?: string` - CSS classes for styling
+- All standard HTML input attributes
+
+## Accessibility Features
+
+Each component includes:
+
+- (^\_^) Semantic HTML elements
+- (^\_^) ARIA attributes and roles
+- (^\_^) Keyboard navigation support
+- (^\_^) Focus management
+- (^\_^) Screen reader announcements
+- (^\_^) Error and validation states
+- (^\_^) Visible focus indicators
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Contributing
+
+Contributions are welcome! Please see our [contributing guidelines](../../CONTRIBUTING.md) for details.
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server
+pnpm dev
+
+# Run type checking
+pnpm check
+
+# Build library
+pnpm build
+
+# Run tests (Vitest)
+pnpm test
+```
+
+## Releasing
+
+Releases are driven by [release-it](https://github.com/release-it/release-it) + `@release-it/conventional-changelog`. Versions auto-bump from [Conventional Commits](https://www.conventionalcommits.org/) (`feat:` → minor, `fix:` → patch, `feat!:` / `BREAKING CHANGE:` → major).
+
+### Prerequisites
+
+- Logged in to npm: `npm whoami` should print your username
+- `GITHUB_TOKEN` env var set (else release-it falls back to the web UI for the GitHub release)
+- Clean working tree on `main`
+
+### Commands
+
+```bash
+cd packages/alus
+
+pnpm release:dry      # preview — no git/npm/github writes
+pnpm release          # interactive — prompts for the bump
+pnpm release:patch    # 0.1.0 → 0.1.1
+pnpm release:minor    # 0.1.0 → 0.2.0
+pnpm release:major    # 0.1.0 → 1.0.0
+```
+
+### What `pnpm release` does
+
+1. `before:init` hook → `pnpm check` (svelte-check must pass)
+2. Bumps `package.json` version
+3. `after:bump` hook → `pnpm build` (regenerates `dist/`)
+4. Writes `CHANGELOG.md` from conventional commits since the last tag
+5. Commits `chore(release): alus-ui v<version>` and tags `alus-ui-v<version>`
+6. Pushes commit + tag to `origin/main`
+7. Creates GitHub release with the changelog body
+8. Publishes to npm (`npm publish` runs `prepublishOnly` → build + test again)
+
+### Commit message conventions
+
+| Prefix       | Section in CHANGELOG | Bump  |
+| ------------ | -------------------- | ----- |
+| `feat:`      | Features             | minor |
+| `fix:`       | Bug Fixes            | patch |
+| `perf:`      | Performance          | patch |
+| `refactor:`  | Refactors            | patch |
+| `docs:`      | Documentation        | patch |
+| `test:`      | Tests                | patch |
+| `build:`     | Build                | patch |
+| `ci:` / `chore:` / `style:` | _(hidden)_ | none |
+
+Append `!` after the type (or include `BREAKING CHANGE:` in the body) for a major bump.
+
+### Config
+
+Settings live in `packages/alus/.release-it.json`. Tag scheme is `alus-ui-v<version>` so future workspace packages can release independently.
+
+## License
+
+MIT
+
+## Repository
+
+- **GitHub**: https://github.com/Hanivan/alus
+- **Issues**: https://github.com/Hanivan/alus/issues
+- **Documentation**: https://github.com/Hanivan/alus#readme
+
+## Acknowledgments
+
+Built with:
+
+- [Svelte 5](https://svelte.dev/) - Cybernetically enhanced web apps
+- [Tailwind CSS](https://tailwindcss.com/) - Utility-first CSS framework
+- [Floating UI](https://floating-ui.com/) - Positioning engine for overlays
+- [Runed](https://runed.dev/) - Svelte 5 utilities library
+
+## Related Projects
+
+- [Showcase App](https://github.com/Hanivan/alus) - Live demo of all alus-ui components
+- [Contributing](https://github.com/Hanivan/alus/blob/main/CONTRIBUTING.md) - How to contribute
+
+---
+
+**Note**: This library is in active development. APIs may change before v1.0 release.

package/dist/components/display/aspect-ratio/AspectRatio.svelte

@@ -0,0 +1,18 @@
+<script lang="ts">
+	interface Props {
+		children?: import('svelte').Snippet;
+		ratio?: number;
+		class?: string;
+		innerClass?: string;
+	}
+
+	let { children, ratio = 1, class: className = '', innerClass = '' }: Props = $props();
+
+	const containerStyle = $derived(`aspect-ratio:${ratio};`);
+</script>
+
+<div class={className} style={containerStyle} data-aspect-ratio={ratio}>
+	<div class={innerClass} style="width:100%;height:100%;">
+		{#if children}{@render children()}{/if}
+	</div>
+</div>

package/dist/components/display/aspect-ratio/AspectRatio.svelte.d.ts

@@ -0,0 +1,9 @@
+interface Props {
+    children?: import('svelte').Snippet;
+    ratio?: number;
+    class?: string;
+    innerClass?: string;
+}
+declare const AspectRatio: import("svelte").Component<Props, {}, "">;
+type AspectRatio = ReturnType<typeof AspectRatio>;
+export default AspectRatio;

package/dist/components/display/aspect-ratio/index.d.ts

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

package/dist/components/display/aspect-ratio/index.js

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

package/dist/components/display/avatar/Avatar.svelte

@@ -0,0 +1,62 @@
+<script lang="ts">
+	import { labelAttrs, mergeAttrs } from '../../../utils/a11y/index.js';
+
+	interface Props {
+		class?: string;
+		src?: string;
+		alt?: string;
+		fallback?: string;
+		size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+		// Accessibility attributes
+		'aria-label'?: string;
+	}
+
+	let {
+		class: className = '',
+		src,
+		alt = '',
+		fallback,
+		size = 'md',
+		'aria-label': ariaLabel
+	}: Props = $props();
+
+	let imgError = $state(false);
+
+	// Build ARIA attributes using reusable utilities
+	let ariaAttrs: Record<string, string> = $derived(
+		mergeAttrs(labelAttrs({ label: ariaLabel || alt }))
+	);
+
+	function getInitials(text: string): string {
+		return text
+			.split(' ')
+			.map((word) => word[0])
+			.join('')
+			.toUpperCase()
+			.slice(0, 2);
+	}
+</script>
+
+<div class={className} data-size={size} {...ariaAttrs}>
+	{#if src && !imgError}
+		<img {src} {alt} aria-hidden="true" onerror={() => (imgError = true)} class="avatar-image" />
+	{:else if fallback}
+		<span class="avatar-fallback" aria-hidden="true">
+			{getInitials(fallback)}
+		</span>
+	{:else}
+		<span class="avatar-placeholder" aria-hidden="true">
+			<svg
+				xmlns="http://www.w3.org/2000/svg"
+				width="24"
+				height="24"
+				viewBox="0 0 24 24"
+				fill="currentColor"
+			>
+				<path
+					d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"
+				/>
+			</svg>
+		</span>
+	{/if}
+</div>

package/dist/components/display/avatar/Avatar.svelte.d.ts

@@ -0,0 +1,11 @@
+interface Props {
+    class?: string;
+    src?: string;
+    alt?: string;
+    fallback?: string;
+    size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    'aria-label'?: string;
+}
+declare const Avatar: import("svelte").Component<Props, {}, "">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/components/display/avatar/index.d.ts

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

package/dist/components/display/avatar/index.js

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

package/dist/components/display/card/Card.svelte

@@ -0,0 +1,60 @@
+<script lang="ts" module>
+	import { getContext, setContext } from 'svelte';
+
+	const KEY = Symbol('alus-ui:card');
+
+	export interface CardContext {
+		titleId: string;
+		descriptionId: string;
+		hasTitle: () => boolean;
+		setHasTitle: (v: boolean) => void;
+		hasDescription: () => boolean;
+		setHasDescription: (v: boolean) => void;
+	}
+
+	export function getCardContext(): CardContext {
+		const ctx = getContext<CardContext | undefined>(KEY);
+		if (!ctx) throw new Error('Card subcomponent must be inside <Card>');
+		return ctx;
+	}
+
+	export function setCardContext(ctx: CardContext) {
+		setContext(KEY, ctx);
+	}
+</script>
+
+<script lang="ts">
+	import { generateCounterId } from '../../../utils/a11y/id.js';
+
+	interface Props {
+		children?: import('svelte').Snippet;
+		class?: string;
+		as?: 'article' | 'section' | 'div';
+	}
+
+	let { children, class: className = '', as = 'article' }: Props = $props();
+
+	let hasTitle = $state(false);
+	let hasDescription = $state(false);
+
+	const titleId = generateCounterId('card-title');
+	const descriptionId = generateCounterId('card-description');
+
+	setCardContext({
+		titleId,
+		descriptionId,
+		hasTitle: () => hasTitle,
+		setHasTitle: (v) => (hasTitle = v),
+		hasDescription: () => hasDescription,
+		setHasDescription: (v) => (hasDescription = v)
+	});
+</script>
+
+<svelte:element
+	this={as}
+	class={className}
+	aria-labelledby={hasTitle ? titleId : undefined}
+	aria-describedby={hasDescription ? descriptionId : undefined}
+>
+	{#if children}{@render children()}{/if}
+</svelte:element>

package/dist/components/display/card/Card.svelte.d.ts

@@ -0,0 +1,18 @@
+export interface CardContext {
+    titleId: string;
+    descriptionId: string;
+    hasTitle: () => boolean;
+    setHasTitle: (v: boolean) => void;
+    hasDescription: () => boolean;
+    setHasDescription: (v: boolean) => void;
+}
+export declare function getCardContext(): CardContext;
+export declare function setCardContext(ctx: CardContext): void;
+interface Props {
+    children?: import('svelte').Snippet;
+    class?: string;
+    as?: 'article' | 'section' | 'div';
+}
+declare const Card: import("svelte").Component<Props, {}, "">;
+type Card = ReturnType<typeof Card>;
+export default Card;

package/dist/components/display/card/CardContent.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+	interface Props {
+		children?: import('svelte').Snippet;
+		class?: string;
+	}
+
+	let { children, class: className = '' }: Props = $props();
+</script>
+
+<div class={className}>
+	{#if children}{@render children()}{/if}
+</div>

package/dist/components/display/card/CardContent.svelte.d.ts

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

package/dist/components/display/card/CardDescription.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+	import { getCardContext } from './Card.svelte';
+
+	interface Props {
+		children?: import('svelte').Snippet;
+		class?: string;
+	}
+
+	let { children, class: className = '' }: Props = $props();
+
+	const ctx = getCardContext();
+
+	$effect(() => {
+		ctx.setHasDescription(true);
+		return () => ctx.setHasDescription(false);
+	});
+</script>
+
+<p id={ctx.descriptionId} class={className}>
+	{#if children}{@render children()}{/if}
+</p>

package/dist/components/display/card/CardDescription.svelte.d.ts

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

package/dist/components/display/card/CardFooter.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+	interface Props {
+		children?: import('svelte').Snippet;
+		class?: string;
+	}
+
+	let { children, class: className = '' }: Props = $props();
+</script>
+
+<footer class={className}>
+	{#if children}{@render children()}{/if}
+</footer>

package/dist/components/display/card/CardFooter.svelte.d.ts

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

package/dist/components/display/card/CardHeader.svelte

@@ -0,0 +1,12 @@
+<script lang="ts">
+	interface Props {
+		children?: import('svelte').Snippet;
+		class?: string;
+	}
+
+	let { children, class: className = '' }: Props = $props();
+</script>
+
+<header class={className}>
+	{#if children}{@render children()}{/if}
+</header>

package/dist/components/display/card/CardHeader.svelte.d.ts

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

package/dist/components/display/card/CardTitle.svelte

@@ -0,0 +1,22 @@
+<script lang="ts">
+	import { getCardContext } from './Card.svelte';
+
+	interface Props {
+		children?: import('svelte').Snippet;
+		class?: string;
+		as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+	}
+
+	let { children, class: className = '', as = 'h3' }: Props = $props();
+
+	const ctx = getCardContext();
+
+	$effect(() => {
+		ctx.setHasTitle(true);
+		return () => ctx.setHasTitle(false);
+	});
+</script>
+
+<svelte:element this={as} id={ctx.titleId} class={className}>
+	{#if children}{@render children()}{/if}
+</svelte:element>

package/dist/components/display/card/CardTitle.svelte.d.ts

@@ -0,0 +1,8 @@
+interface Props {
+    children?: import('svelte').Snippet;
+    class?: string;
+    as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+}
+declare const CardTitle: import("svelte").Component<Props, {}, "">;
+type CardTitle = ReturnType<typeof CardTitle>;
+export default CardTitle;

package/dist/components/display/card/index.d.ts

@@ -0,0 +1,7 @@
+export { default as Card, getCardContext, setCardContext } from './Card.svelte';
+export { default as CardHeader } from './CardHeader.svelte';
+export { default as CardTitle } from './CardTitle.svelte';
+export { default as CardDescription } from './CardDescription.svelte';
+export { default as CardContent } from './CardContent.svelte';
+export { default as CardFooter } from './CardFooter.svelte';
+export type { CardContext } from './Card.svelte';

package/dist/components/display/card/index.js

@@ -0,0 +1,6 @@
+export { default as Card, getCardContext, setCardContext } from './Card.svelte';
+export { default as CardHeader } from './CardHeader.svelte';
+export { default as CardTitle } from './CardTitle.svelte';
+export { default as CardDescription } from './CardDescription.svelte';
+export { default as CardContent } from './CardContent.svelte';
+export { default as CardFooter } from './CardFooter.svelte';