@nqmcreative/ui 0.2.1 → 0.2.2

package/README.md

@@ -1,13 +1,14 @@
 # @nqmcreative/ui
 
-Svelte 5 (runes) + Tailwind CSS v4 component library. One package, **two
+Svelte 5 (runes) + Tailwind CSS v4 component library. One package, **three
 styles**, 65 components each — the same props, the same behaviour, a different
 look. Eight tones, light and dark, no runtime dependencies.
 
-| style   | import                  | character                                                                                                                      |
-| ------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `matte` | `@nqmcreative/ui/matte` | Flat and sharp-cornered — no radius, no shadow, no gloss. Hairline rules and mono micro-labels do the work borders usually do. |
-| `paper` | `@nqmcreative/ui/paper` | The neutral one. Start here if unsure: soft corners, light shadows, generous spacing, and nothing that fights the content.     |
+| style    | import                   | character                                                                                                                      |
+| -------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `matte`  | `@nqmcreative/ui/matte`  | Flat and sharp-cornered — no radius, no shadow, no gloss. Hairline rules and mono micro-labels do the work borders usually do. |
+| `paper`  | `@nqmcreative/ui/paper`  | The neutral one. Start here if unsure: soft corners, light shadows, generous spacing, and nothing that fights the content.     |
+| `sprout` | `@nqmcreative/ui/sprout` | Warm and fully rounded — leaf green on cream, pill buttons, and a round display face. For school, community and family sites.  |
 
 The docs site lives in this repo — every component with a live demo, plus
 theming, locale and contributing guides. `bun run dev` to read it.
@@ -132,6 +133,7 @@ Under SSR use `<LocaleProvider>` instead, so the locale is scoped to a request.
 src/lib/core/            behaviour, a11y, types — no markup, no classes
 src/lib/styles/matte/    65 components
 src/lib/styles/paper/    65 components
+src/lib/styles/sprout/   65 components
 scripts/catalogue.mjs    the list every style must implement
 ```
 

package/dist/styles/sprout/Accordion.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	interface Props extends HTMLAttributes<HTMLDivElement> {
+		children: Snippet;
+	}
+
+	let { class: className = '', children, ...rest }: Props = $props();
+</script>
+
+<div
+	class="flex flex-col overflow-hidden rounded-[20px] border border-hairline bg-bg {className}"
+	{...rest}
+>
+	{@render children()}
+</div>

package/dist/styles/sprout/Accordion.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    children: Snippet;
+}
+declare const Accordion: import("svelte").Component<Props, {}, "">;
+type Accordion = ReturnType<typeof Accordion>;
+export default Accordion;

package/dist/styles/sprout/AccordionItem.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { toneText, type Tone } from '../../core/tones.js';
+
+	interface Props extends HTMLAttributes<HTMLDetailsElement> {
+		title: string;
+		open?: boolean;
+		tone?: Tone;
+		/** Short text on the right of the summary row. */
+		meta?: string;
+		children: Snippet;
+	}
+
+	let {
+		title,
+		open = $bindable(false),
+		tone = 'brand',
+		meta,
+		class: className = '',
+		children,
+		...rest
+	}: Props = $props();
+</script>
+
+<details bind:open class="group border-b border-hairline last:border-b-0 {className}" {...rest}>
+	<summary
+		class="flex cursor-pointer list-none items-center gap-4 px-4 py-3.5 font-sans text-sm font-medium text-text transition-colors duration-150 ease-brand-out select-none hover:bg-bg-alt focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-current [&::-webkit-details-marker]:hidden"
+	>
+		<span class="flex-1">{title}</span>
+		{#if meta}<span class="text-[13px] font-normal text-text-muted">{meta}</span>{/if}
+		<svg
+			class="size-4 shrink-0 transition-transform duration-200 ease-brand-out group-open:rotate-180 {toneText[
+				tone
+			]}"
+			viewBox="0 0 16 16"
+			fill="none"
+			aria-hidden="true"
+		>
+			<path d="m4 6 4 4 4-4" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" />
+		</svg>
+	</summary>
+	<div class="px-4 pb-4 font-sans text-sm leading-relaxed text-text-secondary">
+		{@render children()}
+	</div>
+</details>

package/dist/styles/sprout/AccordionItem.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+interface Props extends HTMLAttributes<HTMLDetailsElement> {
+    title: string;
+    open?: boolean;
+    tone?: Tone;
+    /** Short text on the right of the summary row. */
+    meta?: string;
+    children: Snippet;
+}
+declare const AccordionItem: import("svelte").Component<Props, {}, "open">;
+type AccordionItem = ReturnType<typeof AccordionItem>;
+export default AccordionItem;

package/dist/styles/sprout/Alert.svelte

@@ -0,0 +1,100 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import {
+		toneBorder,
+		toneBorderSoft,
+		toneSurface,
+		toneText,
+		type Tone
+	} from '../../core/tones.js';
+	import { useLocale } from '../../core/locale.svelte.js';
+	import { edge } from './lift.js';
+
+	export type AlertVariant = 'soft' | 'outline' | 'accent';
+
+	interface Props extends HTMLAttributes<HTMLDivElement> {
+		tone?: Tone;
+		variant?: AlertVariant;
+		title?: string;
+		/** Shows a close button and fires `ondismiss`. */
+		dismissible?: boolean;
+		ondismiss?: () => void;
+		/** Replaces the built-in status glyph. */
+		icon?: Snippet;
+		children?: Snippet;
+	}
+
+	let {
+		tone = 'info',
+		variant = 'soft',
+		title,
+		dismissible = false,
+		ondismiss,
+		icon,
+		class: className = '',
+		children,
+		...rest
+	}: Props = $props();
+
+	const t = useLocale();
+	let open = $state(true);
+
+	const variants = $derived({
+		soft: `${toneSurface[tone]} border ${toneBorderSoft[tone]}`,
+		outline: `bg-bg ${edge} border ${toneBorderSoft[tone]}`,
+		accent: `${toneSurface[tone]} border-l-4 ${toneBorder[tone]}`
+	});
+
+	function dismiss() {
+		open = false;
+		ondismiss?.();
+	}
+</script>
+
+{#if open}
+	<div
+		role={tone === 'danger' ? 'alert' : 'status'}
+		class="flex items-start gap-3 rounded-[20px] p-4 font-sans {variants[variant]} {className}"
+		{...rest}
+	>
+		<span class="mt-0.5 shrink-0 {toneText[tone]}">
+			{#if icon}
+				{@render icon()}
+			{:else}
+				<svg class="size-4" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+					<circle cx="8" cy="8" r="6.5" stroke="currentColor" stroke-width="1.5" />
+					<path d="M8 4.75v4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
+					<circle cx="8" cy="11.25" r="0.85" fill="currentColor" />
+				</svg>
+			{/if}
+		</span>
+
+		<div class="flex min-w-0 flex-1 flex-col gap-1">
+			{#if title}
+				<p class="text-sm leading-snug font-semibold {toneText[tone]}">{title}</p>
+			{/if}
+			{#if children}
+				<div class="text-[13px] leading-relaxed text-text-secondary">{@render children()}</div>
+			{/if}
+		</div>
+
+		{#if dismissible}
+			<button
+				type="button"
+				onclick={dismiss}
+				aria-label={t.current.dismiss}
+				class="-m-1 shrink-0 rounded p-1 text-text-muted transition-colors duration-150 hover:bg-bg/60 hover:text-text focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current"
+			>
+				<svg class="size-3.5" viewBox="0 0 14 14" fill="none" aria-hidden="true">
+					<path
+						d="m2 2 10 10M12 2 2 12"
+						stroke="currentColor"
+						stroke-width="1.6"
+						stroke-linecap="round"
+					/>
+				</svg>
+			</button>
+		{/if}
+	</div>
+{/if}

package/dist/styles/sprout/Alert.svelte.d.ts

@@ -0,0 +1,18 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+export type AlertVariant = 'soft' | 'outline' | 'accent';
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    tone?: Tone;
+    variant?: AlertVariant;
+    title?: string;
+    /** Shows a close button and fires `ondismiss`. */
+    dismissible?: boolean;
+    ondismiss?: () => void;
+    /** Replaces the built-in status glyph. */
+    icon?: Snippet;
+    children?: Snippet;
+}
+declare const Alert: import("svelte").Component<Props, {}, "">;
+type Alert = ReturnType<typeof Alert>;
+export default Alert;

package/dist/styles/sprout/Avatar.svelte

@@ -0,0 +1,60 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { toneSoft, type Tone } from '../../core/tones.js';
+
+	export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+	interface Props extends HTMLAttributes<HTMLSpanElement> {
+		src?: string;
+		alt?: string;
+		/** Falls back to the initials of this name when there is no `src`. */
+		name?: string;
+		size?: AvatarSize;
+		tone?: Tone;
+		/** Rounded square instead of the default circle. */
+		squared?: boolean;
+	}
+
+	let {
+		src,
+		alt,
+		name = '',
+		size = 'md',
+		tone = 'brand',
+		squared = false,
+		class: className = '',
+		...rest
+	}: Props = $props();
+
+	const sizes: Record<AvatarSize, string> = {
+		xs: 'size-6 text-[10px]',
+		sm: 'size-8 text-xs',
+		md: 'size-10 text-sm',
+		lg: 'size-12 text-base',
+		xl: 'size-16 text-lg'
+	};
+
+	const initials = $derived(
+		name
+			.trim()
+			.split(/\s+/)
+			.slice(0, 2)
+			.map((part) => part[0] ?? '')
+			.join('')
+			.toUpperCase()
+	);
+</script>
+
+<span
+	class="inline-flex shrink-0 items-center justify-center overflow-hidden font-sans font-semibold select-none
+		{squared ? 'rounded-2xl' : 'rounded-full'} {sizes[size]} {src
+		? 'bg-bg-inset'
+		: toneSoft[tone]} {className}"
+	{...rest}
+>
+	{#if src}
+		<img {src} alt={alt ?? name} class="size-full object-cover" />
+	{:else}
+		{initials}
+	{/if}
+</span>

package/dist/styles/sprout/Avatar.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+interface Props extends HTMLAttributes<HTMLSpanElement> {
+    src?: string;
+    alt?: string;
+    /** Falls back to the initials of this name when there is no `src`. */
+    name?: string;
+    size?: AvatarSize;
+    tone?: Tone;
+    /** Rounded square instead of the default circle. */
+    squared?: boolean;
+}
+declare const Avatar: import("svelte").Component<Props, {}, "">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/styles/sprout/AvatarGroup.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	interface Props extends HTMLAttributes<HTMLDivElement> {
+		children: Snippet;
+	}
+
+	let { class: className = '', children, ...rest }: Props = $props();
+</script>
+
+<div
+	class="flex items-center *:-ml-2 *:ring-2 *:ring-bg [&>*:first-child]:ml-0 {className}"
+	{...rest}
+>
+	{@render children()}
+</div>

package/dist/styles/sprout/AvatarGroup.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    children: Snippet;
+}
+declare const AvatarGroup: import("svelte").Component<Props, {}, "">;
+type AvatarGroup = ReturnType<typeof AvatarGroup>;
+export default AvatarGroup;

package/dist/styles/sprout/Badge.svelte

@@ -0,0 +1,58 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import {
+		toneBorderSoft,
+		toneFill,
+		toneSoft,
+		toneSolid,
+		toneText,
+		type Tone
+	} from '../../core/tones.js';
+
+	export type BadgeVariant = 'soft' | 'solid' | 'outline';
+	export type BadgeSize = 'sm' | 'md';
+
+	interface Props extends HTMLAttributes<HTMLSpanElement> {
+		tone?: Tone;
+		variant?: BadgeVariant;
+		size?: BadgeSize;
+		/** Small filled circle before the label. */
+		dot?: boolean;
+		children: Snippet;
+	}
+
+	let {
+		tone = 'brand',
+		variant = 'soft',
+		size = 'md',
+		dot = false,
+		class: className = '',
+		children,
+		...rest
+	}: Props = $props();
+
+	const variants: Record<BadgeVariant, string> = $derived({
+		soft: toneSoft[tone],
+		solid: toneSolid[tone],
+		outline: `border ${toneBorderSoft[tone]} ${toneText[tone]} bg-bg`
+	});
+
+	const sizes: Record<BadgeSize, string> = {
+		sm: 'px-2.5 py-0.5 text-[11px]',
+		md: 'px-3 py-1 text-xs'
+	};
+</script>
+
+<span
+	class="inline-flex items-center gap-1.5 rounded-full font-heading font-medium tracking-[0.04em]
+		{variants[variant]} {sizes[size]} {className}"
+	{...rest}
+>
+	{#if dot}
+		<span
+			class="size-1.5 shrink-0 rounded-full {variant === 'solid' ? 'bg-current' : toneFill[tone]}"
+		></span>
+	{/if}
+	{@render children()}
+</span>

package/dist/styles/sprout/Badge.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+export type BadgeVariant = 'soft' | 'solid' | 'outline';
+export type BadgeSize = 'sm' | 'md';
+interface Props extends HTMLAttributes<HTMLSpanElement> {
+    tone?: Tone;
+    variant?: BadgeVariant;
+    size?: BadgeSize;
+    /** Small filled circle before the label. */
+    dot?: boolean;
+    children: Snippet;
+}
+declare const Badge: import("svelte").Component<Props, {}, "">;
+type Badge = ReturnType<typeof Badge>;
+export default Badge;

package/dist/styles/sprout/Breadcrumb.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { toneHoverText, type Tone } from '../../core/tones.js';
+	import { useLocale } from '../../core/locale.svelte.js';
+
+	export interface BreadcrumbItem {
+		label: string;
+		href?: string;
+	}
+
+	interface Props extends HTMLAttributes<HTMLElement> {
+		items: BreadcrumbItem[];
+		separator?: string;
+		tone?: Tone;
+	}
+
+	let { items, separator = '/', tone = 'brand', class: className = '', ...rest }: Props = $props();
+
+	const t = useLocale();
+</script>
+
+<nav aria-label={t.current.breadcrumb} class="font-sans text-sm {className}" {...rest}>
+	<ol class="flex flex-wrap items-center gap-1.5">
+		{#each items as item, i (item.label)}
+			<li class="flex items-center gap-1.5">
+				{#if i > 0}
+					<span class="text-hairline-strong select-none" aria-hidden="true">{separator}</span>
+				{/if}
+				{#if item.href && i < items.length - 1}
+					<a
+						href={item.href}
+						class="rounded px-1 py-0.5 text-text-muted transition-colors duration-150 ease-brand-out hover:bg-bg-inset {toneHoverText[
+							tone
+						]}"
+					>
+						{item.label}
+					</a>
+				{:else}
+					<span
+						class="px-1 py-0.5 font-medium text-text"
+						aria-current={i === items.length - 1 ? 'page' : undefined}
+					>
+						{item.label}
+					</span>
+				{/if}
+			</li>
+		{/each}
+	</ol>
+</nav>

package/dist/styles/sprout/Breadcrumb.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+export interface BreadcrumbItem {
+    label: string;
+    href?: string;
+}
+interface Props extends HTMLAttributes<HTMLElement> {
+    items: BreadcrumbItem[];
+    separator?: string;
+    tone?: Tone;
+}
+declare const Breadcrumb: import("svelte").Component<Props, {}, "">;
+type Breadcrumb = ReturnType<typeof Breadcrumb>;
+export default Breadcrumb;

package/dist/styles/sprout/Button.svelte

@@ -0,0 +1,105 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import Spinner from './Spinner.svelte';
+	import {
+		focusRing,
+		toneBorderSoft,
+		toneRing,
+		toneSoft,
+		toneSoftHover,
+		toneSolid,
+		toneSolidHover,
+		toneText,
+		type Tone
+	} from '../../core/tones.js';
+	import { edge, lift } from './lift.js';
+
+	export type ButtonVariant = 'solid' | 'soft' | 'outline' | 'ghost' | 'link' | 'primary';
+	export type ButtonSize = 'sm' | 'md' | 'lg' | 'xl';
+
+	interface Props extends HTMLButtonAttributes {
+		variant?: ButtonVariant;
+		tone?: Tone;
+		size?: ButtonSize;
+		/** Renders an `<a>` instead of a `<button>`. */
+		href?: string;
+		target?: string;
+		rel?: string;
+		loading?: boolean;
+		/** Stretch to the container's full width. */
+		block?: boolean;
+		children: Snippet;
+	}
+
+	let {
+		variant = 'solid',
+		tone = 'brand',
+		size = 'md',
+		href,
+		loading = false,
+		block = false,
+		disabled = false,
+		type = 'button',
+		class: className = '',
+		children,
+		...rest
+	}: Props = $props();
+
+	// Fully round, in the heading face, and standing on a solid lip it sinks
+	// into when pressed: the three things that make a sprout button read as
+	// something to touch rather than something to click. The 3px it travels is
+	// exactly what the lip loses, so the top face lands where the shadow was.
+	const base =
+		'inline-flex items-center justify-center gap-2 rounded-full border font-heading font-semibold whitespace-nowrap transition-[color,background-color,border-color,box-shadow,transform] duration-150 ease-brand-out active:translate-y-[3px] disabled:opacity-50 disabled:pointer-events-none disabled:active:translate-y-0 aria-disabled:opacity-50 aria-disabled:pointer-events-none';
+
+	// Roomier than the other styles' — a pill needs horizontal padding to keep its label
+	// off the curve, and the extra width suits a touch target.
+	const sizes: Record<ButtonSize, string> = {
+		sm: 'h-9 px-4 text-[13px]',
+		md: 'h-11 px-5 text-sm',
+		lg: 'h-12 px-6 text-[15px]',
+		xl: 'h-14 px-8 text-base'
+	};
+
+	const variantClass = $derived.by(() => {
+		switch (variant) {
+			case 'primary':
+			case 'solid':
+				return `border-transparent ${toneSolid[tone]} ${toneSolidHover[tone]} ${lift[tone]}`;
+			case 'soft':
+				return `border-transparent ${toneSoft[tone]} ${toneSoftHover[tone]} ${edge}`;
+			// Outline keeps its own colours on hover — swapping to a solid fill is
+			// matte's move, and it fights sprout's soft surfaces.
+			case 'outline':
+				return `bg-bg ${edge} ${toneText[tone]} ${toneBorderSoft[tone]} hover:bg-bg-alt`;
+			// Nothing raised, so nothing to sink: ghost stays flat on the page.
+			case 'ghost':
+				return `border-transparent bg-transparent ${toneText[tone]} ${toneSoftHover[tone]} active:translate-y-0`;
+			// No pill and no dip: this variant is a sentence, not a target.
+			case 'link':
+				return `border-transparent ${toneText[tone]} h-auto p-0 text-sm underline-offset-4 hover:underline active:translate-y-0`;
+		}
+	});
+
+	const isLink = $derived(variant === 'link');
+	const inert = $derived(disabled || loading);
+</script>
+
+<svelte:element
+	this={href ? 'a' : 'button'}
+	{href}
+	type={href ? undefined : type}
+	disabled={href ? undefined : inert}
+	aria-disabled={href && inert ? 'true' : undefined}
+	aria-busy={loading ? 'true' : undefined}
+	role={href ? 'button' : undefined}
+	class="{base} {focusRing} {toneRing[tone]} {variantClass} {isLink ? '' : sizes[size]}
+		{block ? 'w-full' : ''} {className}"
+	{...rest}
+>
+	{#if loading}
+		<Spinner size={size === 'sm' ? 'xs' : 'sm'} label="" />
+	{/if}
+	{@render children()}
+</svelte:element>

package/dist/styles/sprout/Button.svelte.d.ts

@@ -0,0 +1,21 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+export type ButtonVariant = 'solid' | 'soft' | 'outline' | 'ghost' | 'link' | 'primary';
+export type ButtonSize = 'sm' | 'md' | 'lg' | 'xl';
+interface Props extends HTMLButtonAttributes {
+    variant?: ButtonVariant;
+    tone?: Tone;
+    size?: ButtonSize;
+    /** Renders an `<a>` instead of a `<button>`. */
+    href?: string;
+    target?: string;
+    rel?: string;
+    loading?: boolean;
+    /** Stretch to the container's full width. */
+    block?: boolean;
+    children: Snippet;
+}
+declare const Button: import("svelte").Component<Props, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;