@sveltier/ui 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sveltier contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# Sveltier
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The UI framework for AI coding agents, on Svelte 5.
+
+Coding agents do not remember your library, cannot see the screen, and learn by running and
+fixing. Sveltier is designed around all three, and the same choices help every developer.
+
+- **Finds the right information.** Props tables, `llms.txt` and `llms-full.txt` are generated
+  from the TypeScript types, and the typed sources ship in this package. An agent reads the API
+  of the version it installed, not a guess from its training data.
+- **Gets it right the first time.** `variant`, `size`, `density`, `color` and `rounded` mean the
+  same thing on every component, as literal types: a value that does not exist is a type error
+  that lists the ones that do.
+- **Fixes itself when wrong.** Every error has a stable code, says what happened and what to do,
+  and links to its entry in the docs. Development builds also warn about mistakes that types
+  cannot catch.
+- **Accessible without being asked.** Roles, focus and keys follow the WAI-ARIA Authoring
+  Practices, tested in Chromium, Firefox and WebKit.
+
+> **Alpha.** The API may still change between releases.
+
+## Install
+
+```sh
+npm install @sveltier/ui
+```
+
+Svelte 5.40 or later is required.
+
+## Set up
+
+Wrap the app in `UIProvider` with a theme pack, then use the components anywhere inside it.
+
+```svelte
+<!-- src/routes/+layout.svelte -->
+<script>
+	import { UIProvider } from '@sveltier/ui';
+	import { monolith } from '@sveltier/ui/themes/monolith';
+	let { children } = $props();
+</script>
+
+<!-- Monolith, light or dark following the OS -->
+<UIProvider themes={monolith}>
+	{@render children()}
+</UIProvider>
+```
+
+```svelte
+<script>
+	import { Button, TextField } from '@sveltier/ui';
+	let email = $state('');
+</script>
+
+<TextField label="Email" type="email" required bind:value={email} />
+<Button variant="tonal">Save</Button>
+```
+
+Fonts are not bundled: each theme names its families and falls back to system fonts. See
+[Fonts](https://sveltier.com/getting-started/fonts).
+
+## What is inside
+
+- **Components:** Alert, Avatar, Badge, Button, ButtonGroup, Card, Chip, Divider, Icon, List,
+  ProgressCircular, ProgressLinear, SegmentedControl, Skeleton, Tabs.
+- **Forms:** Form, Field, TextField, Textarea, NumberField and NativeSelect, validated by the
+  HTML constraints first, then your rules.
+- **Primitives** for your own components: focus trap, roving focus, dismissable layers, portal,
+  inert background and scroll lock, anchored positioning, keyboard maps and typeahead, motion,
+  virtual lists.
+- **Theme engine:** five built-in theme packs (Monolith, Heritage, Aurora, Maison and Milano),
+  each in light and dark, with flash-free server rendering. Define your own with `defineTheme`.
+- **Zero runtime dependencies,** and a gzip size budget on every entry.
+
+## Docs
+
+- [sveltier.com](https://sveltier.com)
+- For agents: [llms.txt](https://sveltier.com/llms.txt) and
+  [llms-full.txt](https://sveltier.com/llms-full.txt)
+- [Error codes](https://sveltier.com/errors)
+
+## License
+
+[MIT](./LICENSE)

package/dist/components/Alert/Alert.svelte

@@ -0,0 +1,88 @@
+<script lang="ts">
+	// A message with a type, a title, actions and a close button. See AlertProps for the props.
+	import { useDefaults } from '../../core/defaults/context.js';
+	import { useLocale } from '../../core/locale/locale.js';
+	import { sharedClasses } from '../../core/props/classes.js';
+	import './alert.css';
+	import type { AlertDefaults, AlertProps } from './types.js';
+
+	let {
+		variant,
+		color,
+		density,
+		rounded,
+		type,
+		title,
+		icon = true,
+		open = $bindable(true),
+		closable = false,
+		closeLabel,
+		onclose,
+		prepend,
+		actions,
+		children,
+		class: className,
+		ref = $bindable(null),
+		...rest
+	}: AlertProps = $props();
+
+	const resolve = useDefaults<AlertDefaults>('Alert', {
+		variant: 'tonal',
+		color: 'info',
+		density: 'default',
+		rounded: true
+	});
+	// A colour passed in wins over the type's.
+	const p = $derived(resolve({ variant, color: color ?? type, density, rounded }));
+	const locale = useLocale();
+
+	// Circles, a triangle and their marks on a 24-unit grid, cut out with evenodd.
+	const RING = 'M12 3a9 9 0 1 0 0 18 9 9 0 1 0 0-18zm0 2a7 7 0 1 1 0 14 7 7 0 1 1 0-14z';
+	const ICONS = {
+		info: `${RING}M11 7h2v2h-2zm0 3h2v7h-2z`,
+		success: `${RING}M7.6 12.3 9 10.9l2 2 4-4 1.4 1.4-5.4 5.4z`,
+		warning: 'M12 2.5 1.8 20.5h20.4zm0 4.1 6.7 11.9H5.3zM11 10h2v4h-2zm0 5h2v2h-2z',
+		error: `${RING}M11 7h2v6h-2zm0 8h2v2h-2z`
+	};
+	const CLOSE =
+		'M6.4 5 12 10.6 17.6 5 19 6.4 13.4 12l5.6 5.6-1.4 1.4-5.6-5.6L6.4 19 5 17.6l5.6-5.6L5 6.4z';
+
+	function close() {
+		open = false;
+		onclose?.();
+	}
+</script>
+
+{#if open}
+	<div
+		bind:this={ref}
+		{...rest}
+		role={type === 'warning' || type === 'error' ? 'alert' : 'status'}
+		class={['sv-alert', sharedClasses(p, 'Alert'), className]}
+	>
+		{#if prepend}
+			<span class="sv-alert__icon">{@render prepend()}</span>
+		{:else if icon && type}
+			<span class="sv-alert__icon">
+				<svg viewBox="0 0 24 24" fill="currentColor" fill-rule="evenodd" aria-hidden="true">
+					<path d={ICONS[type]} />
+				</svg>
+			</span>
+		{/if}
+		<div class="sv-alert__content">
+			{#if title}<div class="sv-alert__title">{title}</div>{/if}
+			{#if children}<div>{@render children()}</div>{/if}
+			{#if actions}<div class="sv-alert__actions">{@render actions()}</div>{/if}
+		</div>
+		{#if closable}
+			<button
+				type="button"
+				class="sv-alert__close"
+				aria-label={closeLabel ?? locale.t('close')}
+				onclick={close}
+			>
+				<svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d={CLOSE} /></svg>
+			</button>
+		{/if}
+	</div>
+{/if}

package/dist/components/Alert/Alert.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { AlertProps } from './types.js';
+declare const Alert: import("svelte").Component<AlertProps, {}, "ref" | "open">;
+type Alert = ReturnType<typeof Alert>;
+export default Alert;

package/dist/components/Alert/alert.css

@@ -0,0 +1,78 @@
+@layer sv.tokens, sv.base, sv.components, sv.utilities;
+
+@layer sv.components {
+	/* Icon, message, close, each only when present; padding on the Fibonacci scale. */
+	.sv-alert {
+		display: flex;
+		gap: var(--sv-space-13);
+		align-items: flex-start;
+		box-sizing: border-box;
+		padding: calc(var(--sv-space-13) * var(--sv-density))
+			calc(var(--sv-space-21) * var(--sv-density));
+		border: var(--sv-hairline) solid var(--sv-variant-border);
+		/* The control radius, never rounder than a card, even where controls are pills. */
+		border-radius: var(--sv-rounded, min(var(--sv-radius-md), var(--sv-radius-lg)));
+		background-color: var(--sv-variant-bg);
+		box-shadow: var(--sv-variant-shadow);
+		color: var(--sv-variant-fg);
+		font-size: var(--sv-text-sm);
+		line-height: var(--sv-leading-snug);
+	}
+
+	/* Icons are φ^½ of the text, centred on the first line. */
+	.sv-alert__icon {
+		display: inline-flex;
+		flex: none;
+		block-size: calc(1em * var(--sv-leading-snug));
+		align-items: center;
+	}
+
+	:where(.sv-alert__icon) svg {
+		inline-size: 1.272em;
+		block-size: 1.272em;
+	}
+
+	.sv-alert__content {
+		display: grid;
+		flex: 1;
+		gap: var(--sv-space-5);
+		min-inline-size: 0;
+	}
+
+	.sv-alert__title {
+		font-weight: var(--sv-weight-semibold);
+	}
+
+	.sv-alert__actions {
+		display: flex;
+		flex-wrap: wrap;
+		gap: var(--sv-space-8);
+		margin-block-start: var(--sv-space-5);
+	}
+
+	.sv-alert__close {
+		display: inline-grid;
+		flex: none;
+		place-items: center;
+		inline-size: 1.618em;
+		block-size: 1.618em;
+		margin-block: -0.191em;
+		padding: 0;
+		border: 0;
+		border-radius: 50%;
+		background: transparent;
+		color: inherit;
+		cursor: pointer;
+	}
+
+	@media (hover: hover) {
+		.sv-alert__close:hover {
+			background-color: color-mix(in oklch, currentColor var(--sv-state-hover), transparent);
+		}
+	}
+
+	.sv-alert__close svg {
+		inline-size: 1em;
+		block-size: 1em;
+	}
+}

package/dist/components/Alert/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Alert } from './Alert.svelte';
+export type { AlertDefaults, AlertProps } from './types.js';

package/dist/components/Alert/index.js

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

package/dist/components/Alert/types.d.ts

@@ -0,0 +1,67 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ElementProps } from '../../core/props/element.js';
+import type { Color, Density, Rounded, Variant } from '../../core/props/types.js';
+/** The Alert props that `DefaultsProvider` and `UIProvider` can set for a subtree. */
+export interface AlertDefaults {
+    /**
+     * Visual weight.
+     * @default 'tonal'
+     */
+    variant: Variant;
+    /**
+     * The colour, when there is no `type` to take it from.
+     * @default 'info'
+     */
+    color: Color;
+    /**
+     * Multiplies the padding.
+     * @default 'default'
+     */
+    density: Density;
+    /**
+     * Corner rounding. `true` keeps the theme's radius.
+     * @default true
+     */
+    rounded: Rounded;
+}
+declare module '../../core/defaults/context.js' {
+    interface ComponentDefaults {
+        Alert: AlertDefaults;
+    }
+}
+/** A message about something that happened or needs attention. */
+export type AlertProps = ElementProps<HTMLDivElement, HTMLAttributes<HTMLDivElement>, Partial<AlertDefaults> & {
+    /**
+     * What kind of message: sets the colour and the icon. Warnings and errors are announced at
+     * once (`role="alert"`), the others politely (`role="status"`).
+     */
+    type?: 'info' | 'success' | 'warning' | 'error';
+    /** A short summary, above the text. */
+    title?: string;
+    /**
+     * Shows the icon of the `type`.
+     * @default true
+     */
+    icon?: boolean;
+    /**
+     * Shown while true; a closable alert sets it to false. Bindable.
+     * @default true
+     */
+    open?: boolean;
+    /**
+     * Adds a button that closes the alert and calls `onclose`.
+     * @default false
+     */
+    closable?: boolean;
+    /** The name of the close button. Defaults to the locale's `close`. */
+    closeLabel?: string;
+    /** Called when the close button closes the alert. */
+    onclose?: () => void;
+    /** Content in place of the type's icon. */
+    prepend?: Snippet;
+    /** Buttons or links after the text, such as `Retry`. */
+    actions?: Snippet;
+    /** The message. */
+    children?: Snippet;
+}>;

package/dist/components/Alert/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/Avatar/Avatar.svelte

@@ -0,0 +1,47 @@
+<script lang="ts">
+	// An image with a fallback of initials or an icon. See AvatarProps for the props.
+	import { useDefaults } from '../../core/defaults/context.js';
+	import { sharedClasses } from '../../core/props/classes.js';
+	import './avatar.css';
+	import type { AvatarDefaults, AvatarProps } from './types.js';
+
+	let {
+		size,
+		variant,
+		color,
+		rounded,
+		src,
+		alt,
+		children,
+		class: className,
+		ref = $bindable(null),
+		...rest
+	}: AvatarProps = $props();
+
+	const resolve = useDefaults<AvatarDefaults>('Avatar', {
+		size: 'md',
+		variant: 'tonal',
+		color: 'neutral',
+		rounded: 'full'
+	});
+	const p = $derived(resolve({ size, variant, color, rounded }));
+
+	// The image that failed, so a new src gets its own chance.
+	let failed = $state<string>();
+	const image = $derived(src && src !== failed ? src : undefined);
+</script>
+
+<span
+	bind:this={ref}
+	{...rest}
+	role={alt ? 'img' : undefined}
+	aria-label={alt || undefined}
+	aria-hidden={alt ? undefined : 'true'}
+	class={['sv-avatar', sharedClasses(p, 'Avatar'), className]}
+>
+	{#if image}
+		<img class="sv-avatar__image" src={image} alt="" onerror={() => (failed = image)} />
+	{:else}
+		{@render children?.()}
+	{/if}
+</span>

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

@@ -0,0 +1,4 @@
+import type { AvatarProps } from './types.js';
+declare const Avatar: import("svelte").Component<AvatarProps, {}, "ref">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/components/Avatar/avatar.css

@@ -0,0 +1,34 @@
+@layer sv.tokens, sv.base, sv.components, sv.utilities;
+
+@layer sv.components {
+	/* As tall as a control of its size; initials are φ⁻² of that. */
+	.sv-avatar {
+		position: relative;
+		display: inline-flex;
+		flex: none;
+		align-items: center;
+		justify-content: center;
+		box-sizing: border-box;
+		inline-size: var(--sv-size-height);
+		block-size: var(--sv-size-height);
+		overflow: hidden;
+		border: var(--sv-hairline) solid var(--sv-variant-border);
+		border-radius: var(--sv-rounded, var(--sv-radius-full));
+		background-color: var(--sv-variant-bg);
+		box-shadow: var(--sv-variant-shadow);
+		color: var(--sv-variant-fg);
+		font: var(--sv-weight-medium) calc(var(--sv-size-height) * 0.382) / 1 var(--sv-font-ui);
+		letter-spacing: 0.02em;
+		text-transform: uppercase;
+		vertical-align: middle;
+		user-select: none;
+	}
+
+	.sv-avatar__image {
+		position: absolute;
+		inset: 0;
+		inline-size: 100%;
+		block-size: 100%;
+		object-fit: cover;
+	}
+}

package/dist/components/Avatar/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Avatar } from './Avatar.svelte';
+export type { AvatarDefaults, AvatarProps } from './types.js';

package/dist/components/Avatar/index.js

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

package/dist/components/Avatar/types.d.ts

@@ -0,0 +1,47 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ElementProps } from '../../core/props/element.js';
+import type { Color, Rounded, Size, Variant } from '../../core/props/types.js';
+/** The Avatar props that `DefaultsProvider` and `UIProvider` can set for a subtree. */
+export interface AvatarDefaults {
+    /**
+     * Width and height: the control height of the size.
+     * @default 'md'
+     */
+    size: Size;
+    /**
+     * How the fallback is painted.
+     * @default 'tonal'
+     */
+    variant: Variant;
+    /**
+     * The colour of the fallback.
+     * @default 'neutral'
+     */
+    color: Color;
+    /**
+     * Corner rounding.
+     * @default 'full'
+     */
+    rounded: Rounded;
+}
+declare module '../../core/defaults/context.js' {
+    interface ComponentDefaults {
+        Avatar: AvatarDefaults;
+    }
+}
+/**
+ * A picture of a person or an account: an image, or initials or an icon when there is none
+ * or it fails to load.
+ */
+export type AvatarProps = ElementProps<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>, Partial<AvatarDefaults> & {
+    /** The image. */
+    src?: string;
+    /**
+     * Who or what the avatar shows, for screen readers. Leave it out when a name is shown next
+     * to the avatar: it is then decorative and hidden from them.
+     */
+    alt?: string;
+    /** Initials or an icon, shown while there is no image or it failed to load. */
+    children?: Snippet;
+}>;

package/dist/components/Avatar/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/Badge/Badge.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+	// A count or a dot on its content, or alone in a line. See BadgeProps for the props.
+	import { useDefaults } from '../../core/defaults/context.js';
+	import { sharedClasses } from '../../core/props/classes.js';
+	import '../../styles/visually-hidden.css';
+	import './badge.css';
+	import type { BadgeDefaults, BadgeProps } from './types.js';
+
+	let {
+		color,
+		max,
+		content,
+		dot = false,
+		label,
+		children,
+		id,
+		class: className,
+		ref = $bindable(null),
+		...rest
+	}: BadgeProps = $props();
+
+	const resolve = useDefaults<BadgeDefaults>('Badge', { color: 'primary', max: 99 });
+	const p = $derived(resolve({ color, max }));
+
+	const visible = $derived(dot || (content != null && content !== 0 && content !== ''));
+	const shown = $derived(
+		typeof content === 'number' && content > p.max ? `${p.max}+` : String(content ?? '')
+	);
+	// Screen readers hear the real count, with what it counts.
+	const spoken = $derived(dot ? label : [content, label].filter((part) => part != null).join(' '));
+</script>
+
+<span
+	bind:this={ref}
+	{...rest}
+	{id}
+	class={['sv-badge', !children && 'sv-badge--inline', className]}
+>
+	{@render children?.()}
+	{#if visible}
+		<span class="sv-badge__anchor" aria-hidden="true">
+			<span
+				class={[
+					'sv-badge__badge',
+					sharedClasses({ variant: 'flat', color: p.color }, 'Badge'),
+					dot && 'sv-badge__badge--dot'
+				]}>{dot ? '' : shown}</span
+			>
+		</span>
+		<!-- With an id, the content can point at this text: aria-describedby="{id}-label". -->
+		{#if spoken}<span class="sv-visually-hidden" id={id && `${id}-label`}>{spoken}</span>{/if}
+	{/if}
+</span>

package/dist/components/Badge/Badge.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { BadgeProps } from './types.js';
+declare const Badge: import("svelte").Component<BadgeProps, {}, "ref">;
+type Badge = ReturnType<typeof Badge>;
+export default Badge;

package/dist/components/Badge/badge.css

@@ -0,0 +1,57 @@
+@layer sv.tokens, sv.base, sv.components, sv.utilities;
+
+@layer sv.components {
+	.sv-badge {
+		position: relative;
+		display: inline-flex;
+		flex: none;
+		vertical-align: middle;
+	}
+
+	/*
+	 * A point at the top end corner of the content. The badge is centred on it by flex
+	 * alignment, overflowing evenly, so it follows the writing direction with no direction
+	 * selector (minifiers rewrite :dir() into language guesses for older browsers).
+	 */
+	.sv-badge__anchor {
+		position: absolute;
+		inset-block-start: 0;
+		inset-inline-end: 0;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		inline-size: 0;
+		block-size: 0;
+		pointer-events: none;
+	}
+
+	.sv-badge--inline .sv-badge__anchor {
+		position: static;
+		display: contents;
+	}
+
+	/* A pill φ times its text. */
+	.sv-badge__badge {
+		display: inline-flex;
+		flex: none;
+		align-items: center;
+		justify-content: center;
+		box-sizing: border-box;
+		min-inline-size: 1.618em;
+		block-size: 1.618em;
+		padding-inline: 0.382em;
+		border-radius: var(--sv-radius-full);
+		background-color: var(--sv-variant-bg);
+		color: var(--sv-variant-fg);
+		font: var(--sv-weight-medium) var(--sv-text-label) / 1 var(--sv-font-ui);
+		font-variant-numeric: tabular-nums;
+		white-space: nowrap;
+	}
+
+	.sv-badge__badge--dot {
+		min-inline-size: 0.618em;
+		inline-size: 0.618em;
+		block-size: 0.618em;
+		padding: 0;
+	}
+}

package/dist/components/Badge/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Badge } from './Badge.svelte';
+export type { BadgeDefaults, BadgeProps } from './types.js';

package/dist/components/Badge/index.js

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

package/dist/components/Badge/types.d.ts

@@ -0,0 +1,43 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ElementProps } from '../../core/props/element.js';
+import type { Color } from '../../core/props/types.js';
+/** The Badge props that `DefaultsProvider` and `UIProvider` can set for a subtree. */
+export interface BadgeDefaults {
+    /**
+     * The badge's fill.
+     * @default 'primary'
+     */
+    color: Color;
+    /**
+     * Counts above it show as `max+`.
+     * @default 99
+     */
+    max: number;
+}
+declare module '../../core/defaults/context.js' {
+    interface ComponentDefaults {
+        Badge: BadgeDefaults;
+    }
+}
+/**
+ * A count or a dot pinned to the top end corner of its content, or standing alone in a line
+ * when it has none. A count of 0 hides it.
+ */
+export type BadgeProps = ElementProps<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>, Partial<BadgeDefaults> & {
+    /** What the badge says: usually a count. */
+    content?: number | string;
+    /**
+     * A dot instead of the content.
+     * @default false
+     */
+    dot?: boolean;
+    /**
+     * What the content counts, read after it by screen readers: `unread messages` reads
+     * "3 unread messages". With `dot`, the whole announcement. With an `id`, this text has
+     * the id `{id}-label`, for the `aria-describedby` of a button the badge is pinned to.
+     */
+    label?: string;
+    /** The content the badge is pinned to. */
+    children?: Snippet;
+}>;

package/dist/components/Badge/types.js

@@ -0,0 +1 @@
+export {};