@nqmcreative/ui 0.1.1 → 0.2.1

package/dist/styles/paper/Sidebar.svelte

@@ -0,0 +1,206 @@
+<script module lang="ts">
+	export interface SidebarItem {
+		/** Stable id used for the active state. Falls back to `href`. */
+		id?: string;
+		label: string;
+		href?: string;
+		disabled?: boolean;
+		badge?: string | number;
+		/** Nested links — the parent becomes a collapsible group. */
+		items?: SidebarItem[];
+		/** Open the group on first render. */
+		open?: boolean;
+	}
+
+	export interface SidebarSection {
+		/** Small heading above a run of items. */
+		label?: string;
+		items: SidebarItem[];
+	}
+</script>
+
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { useLocale } from '../../core/locale.svelte.js';
+	import { focusRing, toneRing, toneSoft, type Tone } from '../../core/tones.js';
+
+	interface Props {
+		sections: SidebarSection[];
+		/** Bindable — the `id` (or `href`) of the current item. */
+		value?: string;
+		/** Bindable — narrow rail mode. */
+		collapsed?: boolean;
+		/** Show the collapse button. */
+		collapsible?: boolean;
+		tone?: Tone;
+		header?: Snippet;
+		footer?: Snippet;
+		onnavigate?: (item: SidebarItem) => void;
+		class?: string;
+	}
+
+	let {
+		sections,
+		value = $bindable(''),
+		collapsed = $bindable(false),
+		collapsible = true,
+		tone = 'brand',
+		header,
+		footer,
+		onnavigate,
+		class: className = ''
+	}: Props = $props();
+
+	const t = useLocale();
+
+	const keyOf = (item: SidebarItem) => item.id ?? item.href ?? item.label;
+
+	/** Groups start open when asked, or when they contain the active item. */
+	let opened = $state<Record<string, boolean>>({});
+
+	const isOpen = (item: SidebarItem) =>
+		opened[keyOf(item)] ?? (item.open || item.items!.some((child) => keyOf(child) === value));
+
+	function toggle(item: SidebarItem) {
+		opened = { ...opened, [keyOf(item)]: !isOpen(item) };
+	}
+
+	function go(item: SidebarItem) {
+		if (item.disabled) return;
+		value = keyOf(item);
+		onnavigate?.(item);
+	}
+
+	const row =
+		'flex w-full items-center gap-3 rounded-md px-2.5 py-2 text-left font-sans text-sm transition-colors duration-150 ease-brand-out disabled:pointer-events-none disabled:opacity-40';
+</script>
+
+<aside
+	class="flex h-full shrink-0 flex-col border-r border-hairline bg-bg-alt transition-[width] duration-200 ease-brand-out
+		{collapsed ? 'w-16' : 'w-60'} {className}"
+>
+	{#if header}
+		<div class="flex h-16 shrink-0 items-center gap-3 border-b border-hairline px-3">
+			{@render header()}
+		</div>
+	{/if}
+
+	<nav aria-label={t.current.navigation} class="flex-1 overflow-y-auto p-2">
+		{#each sections as section, i (section.label ?? i)}
+			<div class="flex flex-col gap-0.5 {i > 0 ? 'mt-4' : ''}">
+				{#if section.label && !collapsed}
+					<p class="px-2.5 pb-1 font-sans text-[11px] font-semibold text-text-muted">
+						{section.label}
+					</p>
+				{:else if section.label && collapsed && i > 0}
+					<div class="mx-2 mb-1 h-px bg-hairline" role="separator"></div>
+				{/if}
+
+				{#each section.items as item (keyOf(item))}
+					{#if item.items?.length}
+						<button
+							type="button"
+							onclick={() => toggle(item)}
+							aria-expanded={isOpen(item)}
+							title={collapsed ? item.label : undefined}
+							class="{row} {focusRing} {toneRing[
+								tone
+							]} text-text-secondary hover:bg-bg-inset hover:text-text"
+						>
+							<span class="min-w-0 flex-1 truncate {collapsed ? 'sr-only' : ''}">{item.label}</span>
+							{#if !collapsed}
+								<svg
+									class="size-3.5 shrink-0 transition-transform duration-200 {isOpen(item)
+										? 'rotate-90'
+										: ''}"
+									viewBox="0 0 16 16"
+									fill="none"
+									aria-hidden="true"
+								>
+									<path
+										d="m6 4 4 4-4 4"
+										stroke="currentColor"
+										stroke-width="1.6"
+										stroke-linecap="round"
+									/>
+								</svg>
+							{/if}
+						</button>
+
+						{#if isOpen(item) && !collapsed}
+							<div class="ml-4 flex flex-col gap-0.5 border-l border-hairline pl-2">
+								{#each item.items as child (keyOf(child))}
+									<a
+										href={child.href}
+										onclick={() => go(child)}
+										aria-current={value === keyOf(child) ? 'page' : undefined}
+										class="{row} {focusRing} {toneRing[tone]} {value === keyOf(child)
+											? `${toneSoft[tone]} font-medium`
+											: 'text-text-muted hover:bg-bg-inset hover:text-text'} {child.disabled
+											? 'pointer-events-none opacity-40'
+											: ''}"
+									>
+										<span class="min-w-0 flex-1 truncate">{child.label}</span>
+										{#if child.badge !== undefined}
+											<span class="shrink-0 text-[11px] tabular-nums">{child.badge}</span>
+										{/if}
+									</a>
+								{/each}
+							</div>
+						{/if}
+					{:else}
+						<a
+							href={item.href}
+							onclick={() => go(item)}
+							aria-current={value === keyOf(item) ? 'page' : undefined}
+							title={collapsed ? item.label : undefined}
+							class="{row} {focusRing} {toneRing[tone]} {value === keyOf(item)
+								? `${toneSoft[tone]} font-medium`
+								: 'text-text-secondary hover:bg-bg-inset hover:text-text'} {item.disabled
+								? 'pointer-events-none opacity-40'
+								: ''}"
+						>
+							<span class="min-w-0 flex-1 truncate {collapsed ? 'sr-only' : ''}">{item.label}</span>
+							{#if item.badge !== undefined && !collapsed}
+								<span class="shrink-0 text-[11px] text-text-muted tabular-nums">{item.badge}</span>
+							{/if}
+						</a>
+					{/if}
+				{/each}
+			</div>
+		{/each}
+	</nav>
+
+	{#if footer || collapsible}
+		<div class="flex shrink-0 flex-col gap-2 border-t border-hairline p-2">
+			{#if footer}
+				{@render footer()}
+			{/if}
+			{#if collapsible}
+				<button
+					type="button"
+					onclick={() => (collapsed = !collapsed)}
+					aria-label={collapsed ? t.current.expandSidebar : t.current.collapseSidebar}
+					class="inline-flex h-8 items-center justify-center gap-2 rounded-md font-sans text-xs text-text-muted transition-colors duration-150 hover:bg-bg-inset hover:text-text {focusRing} {toneRing[
+						tone
+					]}"
+				>
+					<svg
+						class="size-4 transition-transform duration-200 {collapsed ? 'rotate-180' : ''}"
+						viewBox="0 0 16 16"
+						fill="none"
+						aria-hidden="true"
+					>
+						<path
+							d="m10 4-4 4 4 4"
+							stroke="currentColor"
+							stroke-width="1.6"
+							stroke-linecap="round"
+						/>
+					</svg>
+					{#if !collapsed}<span>{t.current.collapseSidebar}</span>{/if}
+				</button>
+			{/if}
+		</div>
+	{/if}
+</aside>

package/dist/styles/paper/Sidebar.svelte.d.ts

@@ -0,0 +1,36 @@
+export interface SidebarItem {
+    /** Stable id used for the active state. Falls back to `href`. */
+    id?: string;
+    label: string;
+    href?: string;
+    disabled?: boolean;
+    badge?: string | number;
+    /** Nested links — the parent becomes a collapsible group. */
+    items?: SidebarItem[];
+    /** Open the group on first render. */
+    open?: boolean;
+}
+export interface SidebarSection {
+    /** Small heading above a run of items. */
+    label?: string;
+    items: SidebarItem[];
+}
+import type { Snippet } from 'svelte';
+import { type Tone } from '../../core/tones.js';
+interface Props {
+    sections: SidebarSection[];
+    /** Bindable — the `id` (or `href`) of the current item. */
+    value?: string;
+    /** Bindable — narrow rail mode. */
+    collapsed?: boolean;
+    /** Show the collapse button. */
+    collapsible?: boolean;
+    tone?: Tone;
+    header?: Snippet;
+    footer?: Snippet;
+    onnavigate?: (item: SidebarItem) => void;
+    class?: string;
+}
+declare const Sidebar: import("svelte").Component<Props, {}, "value" | "collapsed">;
+type Sidebar = ReturnType<typeof Sidebar>;
+export default Sidebar;

package/dist/styles/paper/Skeleton.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	export type SkeletonVariant = 'text' | 'block' | 'circle';
+
+	interface Props extends HTMLAttributes<HTMLDivElement> {
+		variant?: SkeletonVariant;
+		/** `text` only — number of stacked lines, the last one runs short. */
+		lines?: number;
+		/** Any CSS length, e.g. `'12rem'` or `'60%'`. */
+		width?: string;
+		height?: string;
+	}
+
+	let {
+		variant = 'text',
+		lines = 1,
+		width,
+		height,
+		class: className = '',
+		...rest
+	}: Props = $props();
+
+	const variants: Record<SkeletonVariant, string> = {
+		text: 'h-4 w-full rounded-md',
+		block: 'h-24 w-full rounded-lg',
+		circle: 'size-10 rounded-full'
+	};
+</script>
+
+{#if variant === 'text' && lines > 1}
+	<div class="flex w-full flex-col gap-2 {className}" {...rest}>
+		{#each { length: lines }, i (i)}
+			<div
+				class="h-4 animate-pulse rounded-md bg-bg-inset {i === lines - 1 ? 'w-2/3' : 'w-full'}"
+				style={width && i !== lines - 1 ? `width:${width}` : undefined}
+			></div>
+		{/each}
+	</div>
+{:else}
+	<div
+		class="animate-pulse bg-bg-inset {variants[variant]} {className}"
+		style="{width ? `width:${width};` : ''}{height ? `height:${height};` : ''}"
+		{...rest}
+	></div>
+{/if}

package/dist/styles/paper/Skeleton.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { HTMLAttributes } from 'svelte/elements';
+export type SkeletonVariant = 'text' | 'block' | 'circle';
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    variant?: SkeletonVariant;
+    /** `text` only — number of stacked lines, the last one runs short. */
+    lines?: number;
+    /** Any CSS length, e.g. `'12rem'` or `'60%'`. */
+    width?: string;
+    height?: string;
+}
+declare const Skeleton: import("svelte").Component<Props, {}, "">;
+type Skeleton = ReturnType<typeof Skeleton>;
+export default Skeleton;

package/dist/styles/paper/Slider.svelte

@@ -0,0 +1,80 @@
+<script lang="ts">
+	import type { HTMLInputAttributes } from 'svelte/elements';
+	import { toneText, type Tone } from '../../core/tones.js';
+	import { percentOf } from '../../core/number.js';
+
+	interface Props extends Omit<HTMLInputAttributes, 'size' | 'type' | 'value' | 'min' | 'max'> {
+		value?: number;
+		min?: number;
+		max?: number;
+		step?: number;
+		tone?: Tone;
+		label?: string;
+		/** Prints the current value on the right of the label row. */
+		showValue?: boolean;
+		/** Appended to the printed value, e.g. `'%'`. */
+		unit?: string;
+		/** Tick labels under the track — usually just `[min, max]`. */
+		marks?: (number | string)[];
+	}
+
+	let {
+		value = $bindable(50),
+		min = 0,
+		max = 100,
+		step = 1,
+		tone = 'brand',
+		label,
+		showValue = false,
+		unit = '',
+		marks,
+		disabled = false,
+		class: className = '',
+		...rest
+	}: Props = $props();
+
+	const pct = $derived(percentOf(value, min, max));
+
+	// The filled part of the track and the thumb both paint with `currentColor`,
+	// so a single tone class on the input drives every vendor pseudo-element.
+	// The gradient classes below are spelled out twice on purpose: Tailwind only
+	// sees literal class strings, so a shared JS constant would produce nothing.
+</script>
+
+<div class="flex w-full flex-col gap-2 {disabled ? 'opacity-50' : ''} {className}">
+	{#if label || showValue}
+		<div class="flex items-baseline justify-between gap-4 font-sans text-sm">
+			{#if label}<span class="text-text-secondary">{label}</span>{/if}
+			{#if showValue}
+				<span class="text-sm font-medium tabular-nums {toneText[tone]}">{value}{unit}</span>
+			{/if}
+		</div>
+	{/if}
+
+	<input
+		type="range"
+		bind:value
+		{min}
+		{max}
+		{step}
+		{disabled}
+		aria-label={label}
+		style="--pct:{pct}%"
+		class="h-5 w-full cursor-pointer appearance-none bg-transparent focus:outline-none disabled:cursor-not-allowed
+			{toneText[tone]}
+			focus-visible:outline-2 focus-visible:outline-offset-4
+			[&::-moz-range-thumb]:size-4 [&::-moz-range-thumb]:rounded-full
+			[&::-moz-range-thumb]:border-2 [&::-moz-range-thumb]:border-bg [&::-moz-range-thumb]:bg-current [&::-moz-range-thumb]:shadow-sm [&::-moz-range-track]:h-1.5 [&::-moz-range-track]:rounded-full [&::-moz-range-track]:bg-[linear-gradient(to_right,currentColor_var(--pct),var(--color-bg-inset)_var(--pct))] [&::-webkit-slider-runnable-track]:h-1.5 [&::-webkit-slider-runnable-track]:rounded-full [&::-webkit-slider-runnable-track]:bg-[linear-gradient(to_right,currentColor_var(--pct),var(--color-bg-inset)_var(--pct))]
+			[&::-webkit-slider-thumb]:-mt-[5px] [&::-webkit-slider-thumb]:size-4 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:border-2
+			[&::-webkit-slider-thumb]:border-bg [&::-webkit-slider-thumb]:bg-current [&::-webkit-slider-thumb]:shadow-sm"
+		{...rest}
+	/>
+
+	{#if marks?.length}
+		<div class="flex justify-between text-[11px] text-text-muted tabular-nums">
+			{#each marks as mark (mark)}
+				<span>{mark}</span>
+			{/each}
+		</div>
+	{/if}
+</div>

package/dist/styles/paper/Slider.svelte.d.ts

@@ -0,0 +1,19 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+interface Props extends Omit<HTMLInputAttributes, 'size' | 'type' | 'value' | 'min' | 'max'> {
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    tone?: Tone;
+    label?: string;
+    /** Prints the current value on the right of the label row. */
+    showValue?: boolean;
+    /** Appended to the printed value, e.g. `'%'`. */
+    unit?: string;
+    /** Tick labels under the track — usually just `[min, max]`. */
+    marks?: (number | string)[];
+}
+declare const Slider: import("svelte").Component<Props, {}, "value">;
+type Slider = ReturnType<typeof Slider>;
+export default Slider;

package/dist/styles/paper/Spinner.svelte

@@ -0,0 +1,34 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { toneText, type Tone } from '../../core/tones.js';
+	import { useLocale } from '../../core/locale.svelte.js';
+
+	export type SpinnerSize = 'xs' | 'sm' | 'md' | 'lg';
+
+	interface Props extends HTMLAttributes<HTMLSpanElement> {
+		size?: SpinnerSize;
+		/** Omit to inherit the parent's `currentColor` (e.g. inside a Button). */
+		tone?: Tone;
+		/** Defaults to the locale's loading string; pass `''` to hide it. */
+		label?: string;
+	}
+
+	const t = useLocale();
+
+	let { size = 'md', tone, label, class: className = '', ...rest }: Props = $props();
+
+	const sizes: Record<SpinnerSize, string> = {
+		xs: 'size-3 border-[1.5px]',
+		sm: 'size-4 border-2',
+		md: 'size-5 border-2',
+		lg: 'size-8 border-[3px]'
+	};
+</script>
+
+<span
+	role="status"
+	aria-label={label ?? t.current.loading}
+	class="inline-block shrink-0 animate-spin rounded-full border-current/25 border-t-current
+		{sizes[size]} {tone ? toneText[tone] : ''} {className}"
+	{...rest}
+></span>

package/dist/styles/paper/Spinner.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+export type SpinnerSize = 'xs' | 'sm' | 'md' | 'lg';
+interface Props extends HTMLAttributes<HTMLSpanElement> {
+    size?: SpinnerSize;
+    /** Omit to inherit the parent's `currentColor` (e.g. inside a Button). */
+    tone?: Tone;
+    /** Defaults to the locale's loading string; pass `''` to hide it. */
+    label?: string;
+}
+declare const Spinner: import("svelte").Component<Props, {}, "">;
+type Spinner = ReturnType<typeof Spinner>;
+export default Spinner;

package/dist/styles/paper/Stat.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { toneText, type Tone } from '../../core/tones.js';
+
+	export type StatTrend = 'up' | 'down' | 'flat';
+
+	interface Props extends HTMLAttributes<HTMLDivElement> {
+		label: string;
+		value: string | number;
+		/** Secondary figure, e.g. `'+12.4%'`. */
+		delta?: string;
+		trend?: StatTrend;
+		hint?: string;
+		/** Colour of the value itself. Leave unset for plain `text`. */
+		tone?: Tone;
+	}
+
+	let {
+		label,
+		value,
+		delta,
+		trend = 'flat',
+		hint,
+		tone,
+		class: className = '',
+		...rest
+	}: Props = $props();
+
+	const trendTone: Record<StatTrend, Tone> = { up: 'success', down: 'danger', flat: 'neutral' };
+	const trendGlyph: Record<StatTrend, string> = { up: '↑', down: '↓', flat: '→' };
+</script>
+
+<div class="flex flex-col gap-1 font-sans {className}" {...rest}>
+	<span class="text-sm font-medium text-text-muted">{label}</span>
+	<div class="flex items-baseline gap-2">
+		<span
+			class="font-heading text-3xl font-semibold tracking-tight tabular-nums {tone
+				? toneText[tone]
+				: 'text-text'}"
+		>
+			{value}
+		</span>
+		{#if delta}
+			<span class="text-sm font-medium {toneText[trendTone[trend]]}">
+				{trendGlyph[trend]}
+				{delta}
+			</span>
+		{/if}
+	</div>
+	{#if hint}<span class="text-sm text-text-muted">{hint}</span>{/if}
+</div>

package/dist/styles/paper/Stat.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import { type Tone } from '../../core/tones.js';
+export type StatTrend = 'up' | 'down' | 'flat';
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    label: string;
+    value: string | number;
+    /** Secondary figure, e.g. `'+12.4%'`. */
+    delta?: string;
+    trend?: StatTrend;
+    hint?: string;
+    /** Colour of the value itself. Leave unset for plain `text`. */
+    tone?: Tone;
+}
+declare const Stat: import("svelte").Component<Props, {}, "">;
+type Stat = ReturnType<typeof Stat>;
+export default Stat;

package/dist/styles/paper/StatsBand.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+	import type { HTMLAttributes } from 'svelte/elements';
+	import Stat from './Stat.svelte';
+	import type { StatTrend } from './Stat.svelte';
+	import type { Tone } from '../../core/tones.js';
+
+	export interface BandStat {
+		label: string;
+		value: string | number;
+		delta?: string;
+		trend?: StatTrend;
+		hint?: string;
+		tone?: Tone;
+	}
+
+	interface Props extends HTMLAttributes<HTMLElement> {
+		stats: BandStat[];
+		title?: string;
+		/** Figures in one bordered card rather than free-standing. */
+		bordered?: boolean;
+	}
+
+	let { stats, title, bordered = true, class: className = '', ...rest }: Props = $props();
+
+	const cols = $derived(
+		stats.length === 2
+			? 'sm:grid-cols-2'
+			: stats.length === 4
+				? 'sm:grid-cols-2 lg:grid-cols-4'
+				: 'sm:grid-cols-3'
+	);
+</script>
+
+<section class="w-full px-6 py-16 {className}" {...rest}>
+	<div class="mx-auto flex w-full max-w-6xl flex-col gap-8">
+		{#if title}
+			<h2
+				class="max-w-xl font-heading text-3xl font-semibold tracking-tight text-balance text-text"
+			>
+				{title}
+			</h2>
+		{/if}
+
+		<div
+			class="grid {cols} {bordered
+				? 'gap-px overflow-hidden rounded-lg border border-hairline bg-hairline shadow-xs'
+				: 'gap-8'}"
+		>
+			{#each stats as stat (stat.label)}
+				<div class={bordered ? 'bg-bg p-6' : ''}>
+					<Stat
+						label={stat.label}
+						value={stat.value}
+						delta={stat.delta}
+						trend={stat.trend}
+						hint={stat.hint}
+						tone={stat.tone}
+					/>
+				</div>
+			{/each}
+		</div>
+	</div>
+</section>

package/dist/styles/paper/StatsBand.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { StatTrend } from './Stat.svelte';
+import type { Tone } from '../../core/tones.js';
+export interface BandStat {
+    label: string;
+    value: string | number;
+    delta?: string;
+    trend?: StatTrend;
+    hint?: string;
+    tone?: Tone;
+}
+interface Props extends HTMLAttributes<HTMLElement> {
+    stats: BandStat[];
+    title?: string;
+    /** Figures in one bordered card rather than free-standing. */
+    bordered?: boolean;
+}
+declare const StatsBand: import("svelte").Component<Props, {}, "">;
+type StatsBand = ReturnType<typeof StatsBand>;
+export default StatsBand;