@dorsk/tsumikit 0.25.0 → 0.26.0

package/README.md

@@ -145,7 +145,8 @@ for a light theme (`:root` defaults to dark, so dark themes may omit it).
 ## Components
 
 **Atoms:** Text, Heading, Button, Input, Textarea, Select, Switch, Checkbox,
-Slider, Progress, Card (`tone` tints the surface for inline banners), Badge
+Slider, Progress, Artwork (lazy cover image with seeded gradient + initials
+fallback, `aspect`, `status` overlay), Card (`tone` tints the surface for inline banners), Badge
 (`tone` semantic palette or `color` for any CSS colour, `size` xs/sm/md, `dot`,
 `icon`, `numeric`, `truncate`, `variant="text"`; all tints derive from
 `--badge-tone`), Dot (`ring` dark halo over artwork), Link (`tone`, `underline`
@@ -174,7 +175,9 @@ the content column only, `stickySidebar` pins it to the viewport, and
 `sidebarPadding="none" | "sm" | "md"` sets the aside gutter — the header and its
 children are `min-width: 0` so a wide title/actions row can't widen the grid on
 mobile), NavItem
-(collapses to an icon rail when the sidebar is narrow), Container, Stack
+(collapses to an icon rail when the sidebar is narrow; `icon` from the
+registry, `iconPath` / `iconChildren` for custom glyphs, `activeStyle="bar"`
+for the inset-bar active look), Container, Stack
 (vertical), Cluster (wrapping row; `stackAt="xs|sm|md|lg"` makes it its own
 query container and stacks children full-width below 18/30/40/48rem — phone
 action rows without a viewport query), AutoGrid (intrinsically responsive
@@ -321,6 +324,22 @@ error | done, `onload`, `label`, `loadingLabel`, `errorLabel`, `retryLabel`,
 </SectionHeader>
 ```
 
+### Artwork
+
+`Artwork` is the one cover/thumbnail tile: `src` + `alt` (required) render a
+lazy, async-decoded `<img>`; a missing or failing source swaps to a gradient
+seeded from `seed` (default `alt`) with `fallback` initials | icon | none.
+`aspect` ('1/1', '2/3', '16/9' or any ratio), `size` (width), `radius`
+sm | md | lg | pill, `fit` cover | contain, `hover` for tappable tiles,
+`status` snippet overlaid bottom-right, `onerror`. `artworkGradient(seed)`,
+`artworkHue(seed)` and `initials(text)` are exported for non-component use.
+
+```svelte
+<Artwork src={album.cover} alt={album.title} aspect="1/1" size="9rem" hover>
+  {#snippet status()}<Dot status="active" ring />{/snippet}
+</Artwork>
+```
+
 ## Container queries
 
 AppShell's `main` and `sidebar` are query containers (`container-name: main` /

package/dist/artwork.d.ts

@@ -0,0 +1,7 @@
+/** Hue (0–359) derived from `seed`; stable across runs and environments. */
+export declare function artworkHue(seed: string): number;
+/** CSS `linear-gradient(...)` for the artwork fallback, keyed on `seed`. */
+export declare function artworkGradient(seed: string): string;
+/** Up to two uppercase initials: first letters of the first two words, or the
+ *  first two characters of a single word. Empty input yields ''. */
+export declare function initials(text: string): string;

package/dist/artwork.js

@@ -0,0 +1,28 @@
+// Placeholder look for missing artwork: a deterministic hue from `seed` so the
+// same album/show always gets the same tint, tinted over the surface tokens so
+// the fallback tracks the active theme instead of being a fixed dark gradient.
+function hash(text) {
+    let h = 0;
+    for (const ch of text) {
+        h = (h * 31 + (ch.codePointAt(0) ?? 0)) >>> 0;
+    }
+    return h;
+}
+/** Hue (0–359) derived from `seed`; stable across runs and environments. */
+export function artworkHue(seed) {
+    return hash(seed) % 360;
+}
+/** CSS `linear-gradient(...)` for the artwork fallback, keyed on `seed`. */
+export function artworkGradient(seed) {
+    const h = artworkHue(seed);
+    return `linear-gradient(160deg, color-mix(in srgb, hsl(${h} 60% 55%) 28%, var(--bg-elevated-2)), color-mix(in srgb, hsl(${h} 60% 40%) 16%, var(--bg-elevated)))`;
+}
+/** Up to two uppercase initials: first letters of the first two words, or the
+ *  first two characters of a single word. Empty input yields ''. */
+export function initials(text) {
+    const words = text.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return '';
+    const picked = words.length === 1 ? [...words[0]].slice(0, 2) : words.slice(0, 2).map((w) => [...w][0]);
+    return picked.join('').toUpperCase();
+}

package/dist/components/atoms/Artwork.svelte

@@ -0,0 +1,152 @@
+<script lang="ts">
+	// Cover / thumbnail tile: a lazy <img> that swaps to a seeded gradient with
+	// initials (or an icon) when there is no source or it fails to load. Width
+	// comes from `size`, height from `aspect`; `status` overlays a Dot/Badge in
+	// the bottom-right corner.
+	import type { Snippet } from 'svelte';
+	import { artworkGradient, initials as initialsOf } from '../../artwork';
+	import Icon from './Icon.svelte';
+	import type { IconName } from './Icon.svelte';
+
+	let {
+		src,
+		alt,
+		seed,
+		aspect = '1/1',
+		size,
+		radius = 'md',
+		fit = 'cover',
+		fallback = 'initials',
+		icon = 'image',
+		status,
+		hover = false,
+		onerror,
+		class: klass = '',
+		...rest
+	}: {
+		src?: string | null;
+		alt: string;
+		/** Drives the gradient hue and the initials. Defaults to `alt`. */
+		seed?: string;
+		/** CSS aspect-ratio, e.g. '1/1', '2/3', '16/9'. */
+		aspect?: '1/1' | '2/3' | '16/9' | (string & {});
+		/** Width (any CSS length). Omit to fill the container. */
+		size?: string;
+		radius?: 'sm' | 'md' | 'lg' | 'pill';
+		fit?: 'cover' | 'contain';
+		fallback?: 'initials' | 'icon' | 'none';
+		/** Glyph shown when `fallback="icon"`. */
+		icon?: IconName;
+		/** Overlay rendered bottom-right (a Dot or Badge). */
+		status?: Snippet;
+		/** Stronger border + shadow on hover, for tappable tiles. */
+		hover?: boolean;
+		onerror?: () => void;
+		class?: string;
+		[key: string]: unknown;
+	} = $props();
+
+	let failed = $state(false);
+	$effect(() => {
+		src;
+		failed = false;
+	});
+
+	const key = $derived(seed ?? alt);
+	const showImage = $derived(Boolean(src) && !failed);
+	const gradient = $derived(showImage ? undefined : artworkGradient(key));
+	const text = $derived(fallback === 'initials' ? initialsOf(key) : '');
+
+	function fail() {
+		failed = true;
+		onerror?.();
+	}
+</script>
+
+<div
+	data-tsu="Artwork"
+	class="artwork r-{radius} {klass}"
+	class:hover
+	style:aspect-ratio={aspect}
+	style:width={size}
+	style:background={gradient}
+	role={showImage ? undefined : 'img'}
+	aria-label={showImage ? undefined : alt}
+	{...rest}
+>
+	{#if showImage}
+		<img {src} {alt} class="img fit-{fit}" loading="lazy" decoding="async" onerror={fail} />
+	{:else if fallback === 'initials' && text}
+		<span class="initials" aria-hidden="true">{text}</span>
+	{:else if fallback === 'icon'}
+		<span class="glyph" aria-hidden="true"><Icon name={icon} /></span>
+	{/if}
+	{#if status}
+		<span class="status">{@render status()}</span>
+	{/if}
+</div>
+
+<style>
+	.artwork {
+		position: relative;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		overflow: hidden;
+		flex: none;
+		background: var(--bg-elevated-2);
+		border: 1px solid var(--border);
+		color: var(--text-muted);
+		container-type: inline-size;
+		transition:
+			border-color 0.12s var(--ease),
+			box-shadow 0.12s var(--ease);
+	}
+	.r-sm {
+		border-radius: var(--r-sm);
+	}
+	.r-md {
+		border-radius: var(--r-md);
+	}
+	.r-lg {
+		border-radius: var(--r-lg);
+	}
+	.r-pill {
+		border-radius: var(--r-pill);
+	}
+	.hover:hover {
+		border-color: var(--border-strong);
+		box-shadow: var(--shadow-md);
+	}
+	.img {
+		position: absolute;
+		inset: 0;
+		width: 100%;
+		height: 100%;
+		display: block;
+	}
+	.fit-cover {
+		object-fit: cover;
+	}
+	.fit-contain {
+		object-fit: contain;
+	}
+	.initials {
+		font-size: 28cqw;
+		font-weight: var(--fw-semibold);
+		letter-spacing: 0.04em;
+		color: color-mix(in srgb, var(--text) 55%, transparent);
+		user-select: none;
+	}
+	.glyph {
+		font-size: 30cqw;
+		display: flex;
+		color: color-mix(in srgb, var(--text) 40%, transparent);
+	}
+	.status {
+		position: absolute;
+		right: var(--sp-2);
+		bottom: var(--sp-2);
+		display: flex;
+	}
+</style>

package/dist/components/atoms/Artwork.svelte.d.ts

@@ -0,0 +1,27 @@
+import type { Snippet } from 'svelte';
+import type { IconName } from './Icon.svelte';
+type $$ComponentProps = {
+    src?: string | null;
+    alt: string;
+    /** Drives the gradient hue and the initials. Defaults to `alt`. */
+    seed?: string;
+    /** CSS aspect-ratio, e.g. '1/1', '2/3', '16/9'. */
+    aspect?: '1/1' | '2/3' | '16/9' | (string & {});
+    /** Width (any CSS length). Omit to fill the container. */
+    size?: string;
+    radius?: 'sm' | 'md' | 'lg' | 'pill';
+    fit?: 'cover' | 'contain';
+    fallback?: 'initials' | 'icon' | 'none';
+    /** Glyph shown when `fallback="icon"`. */
+    icon?: IconName;
+    /** Overlay rendered bottom-right (a Dot or Badge). */
+    status?: Snippet;
+    /** Stronger border + shadow on hover, for tappable tiles. */
+    hover?: boolean;
+    onerror?: () => void;
+    class?: string;
+    [key: string]: unknown;
+};
+declare const Artwork: import("svelte").Component<$$ComponentProps, {}, "">;
+type Artwork = ReturnType<typeof Artwork>;
+export default Artwork;

package/dist/components/atoms/Icon.svelte

@@ -5,7 +5,7 @@
 	// e.g. a lucide-svelte component's contents — without adding it to the
 	// registry. Sized at 1em so it tracks the surrounding text (and the
 	// --fs-scale font control).
-	const ICONS = {
+	const GLYPHS = {
 		// — navigation / chevrons —
 		back: '<path d="m12 19-7-7 7-7" /><path d="M19 12H5" />',
 		'arrow-right': '<path d="M5 12h14" /><path d="m12 5 7 7-7 7" />',
@@ -55,6 +55,7 @@
 		folder: '<path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z" />',
 		archive: '<rect width="20" height="5" x="2" y="3" rx="1" /><path d="M4 8v11a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8" /><path d="M10 12h4" />',
 		image: '<rect width="18" height="18" x="3" y="3" rx="2" ry="2" /><circle cx="9" cy="9" r="2" /><path d="m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21" />',
+		book: '<path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20" />',
 		markdown: '<rect x="3" y="5" width="18" height="14" rx="2" /><path d="M7 15V9l3 3 3-3v6" /><path d="m15 11 2 2 2-2" />',
 		list: '<path d="M3 5h.01" /><path d="M3 12h.01" /><path d="M3 19h.01" /><path d="M8 5h13" /><path d="M8 12h13" /><path d="M8 19h13" />',
 		grid: '<rect width="7" height="7" x="3" y="3" rx="1" /><rect width="7" height="7" x="14" y="3" rx="1" /><rect width="7" height="7" x="14" y="14" rx="1" /><rect width="7" height="7" x="3" y="14" rx="1" />',
@@ -93,6 +94,9 @@
 		'alert-circle': '<circle cx="12" cy="12" r="10" /><line x1="12" x2="12" y1="8" y2="12" /><line x1="12" x2="12.01" y1="16" y2="16" />',
 	} as const;
 
+	// Alternate names resolving to the same path data.
+	const ICONS = { ...GLYPHS, alert: GLYPHS.warning } as const;
+
 	export type IconName = keyof typeof ICONS;
 
 	/** True when `s` is a registered glyph name (vs. e.g. a raw emoji string). */

package/dist/components/atoms/Icon.svelte.d.ts

@@ -1,4 +1,5 @@
 declare const ICONS: {
+    readonly alert: "<path d=\"m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3\" /><path d=\"M12 9v4\" /><path d=\"M12 17h.01\" />";
     readonly back: "<path d=\"m12 19-7-7 7-7\" /><path d=\"M19 12H5\" />";
     readonly 'arrow-right': "<path d=\"M5 12h14\" /><path d=\"m12 5 7 7-7 7\" />";
     readonly 'arrow-up': "<path d=\"m5 12 7-7 7 7\" /><path d=\"M12 19V5\" />";
@@ -39,6 +40,7 @@ declare const ICONS: {
     readonly folder: "<path d=\"M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z\" />";
     readonly archive: "<rect width=\"20\" height=\"5\" x=\"2\" y=\"3\" rx=\"1\" /><path d=\"M4 8v11a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8\" /><path d=\"M10 12h4\" />";
     readonly image: "<rect width=\"18\" height=\"18\" x=\"3\" y=\"3\" rx=\"2\" ry=\"2\" /><circle cx=\"9\" cy=\"9\" r=\"2\" /><path d=\"m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21\" />";
+    readonly book: "<path d=\"M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20\" />";
     readonly markdown: "<rect x=\"3\" y=\"5\" width=\"18\" height=\"14\" rx=\"2\" /><path d=\"M7 15V9l3 3 3-3v6\" /><path d=\"m15 11 2 2 2-2\" />";
     readonly list: "<path d=\"M3 5h.01\" /><path d=\"M3 12h.01\" /><path d=\"M3 19h.01\" /><path d=\"M8 5h13\" /><path d=\"M8 12h13\" /><path d=\"M8 19h13\" />";
     readonly grid: "<rect width=\"7\" height=\"7\" x=\"3\" y=\"3\" rx=\"1\" /><rect width=\"7\" height=\"7\" x=\"14\" y=\"3\" rx=\"1\" /><rect width=\"7\" height=\"7\" x=\"14\" y=\"14\" rx=\"1\" /><rect width=\"7\" height=\"7\" x=\"3\" y=\"14\" rx=\"1\" />";

package/dist/components/layouts/NavItem.svelte

@@ -6,6 +6,8 @@
 	// collapses to a small dot indicator so the count cue survives the rail.
 	// `title`/`aria-label` carry the name so the icon-only state stays accessible
 	// and shows a tooltip. Renders an <a> when `href` is set, else a <button>.
+	// The glyph is `iconChildren` (raw 24×24 SVG content), else `iconPath`
+	// (single path d), else the registry `icon`.
 	import type { Snippet } from 'svelte';
 	import Icon from '../atoms/Icon.svelte';
 	import type { IconName } from '../atoms/Icon.svelte';
@@ -15,19 +17,31 @@
 
 	let {
 		icon,
+		iconChildren,
+		iconPath,
+		iconSize = 18,
 		label,
 		href,
 		active = false,
+		activeStyle = 'fill',
 		onclick,
 		badge,
 		badgeTone = 'neutral',
 		children,
 		...rest
 	}: {
-		icon: IconName;
+		icon?: IconName;
+		/** Raw 24×24 SVG content, for glyphs outside the registry. Wins over `iconPath` and `icon`. */
+		iconChildren?: Snippet;
+		/** Single `<path d>` for a 24×24 outline glyph. Wins over `icon`. */
+		iconPath?: string;
+		iconSize?: number;
 		label: string;
 		href?: string;
 		active?: boolean;
+		/** 'fill' = accent-tinted pill with a rounded left marker; 'bar' = lighter
+		 *  tint with a flat 2px inset accent bar. */
+		activeStyle?: 'fill' | 'bar';
 		onclick?: (e: MouseEvent) => void;
 		/** Optional trailing count pill (e.g. unread / missing items). When the
 		 *  item is `active` it adopts the accent fill; otherwise it uses `badgeTone`. */
@@ -49,13 +63,20 @@
 	type={href ? undefined : 'button'}
 	class="nav-item"
 	class:active
+	class:bar={activeStyle === 'bar'}
 	title={label}
 	aria-label={label}
 	aria-current={active ? 'page' : undefined}
 	{onclick}
 	{...rest}
 >
-	<Icon name={icon} size={18} />
+	{#if iconChildren}
+		<Icon size={iconSize}>{@render iconChildren()}</Icon>
+	{:else if iconPath}
+		<Icon size={iconSize}><path d={iconPath} /></Icon>
+	{:else if icon}
+		<Icon name={icon} size={iconSize} />
+	{/if}
 	<span class="nav-label">{label}</span>
 	{#if hasBadge}
 		<span class="nav-trail">
@@ -101,7 +122,7 @@
 	}
 	/* Active-route accent inset: a left rail marker that survives the icon-rail
 	   collapse (the tint background does too, but the marker reads at a glance). */
-	.nav-item.active::before {
+	.nav-item.active:not(.bar)::before {
 		content: '';
 		position: absolute;
 		left: 0;
@@ -112,6 +133,12 @@
 		border-radius: var(--r-pill);
 		background: var(--accent);
 	}
+	.nav-item.bar.active {
+		background: color-mix(in srgb, var(--accent) 10%, transparent);
+		box-shadow: inset 2px 0 0 var(--accent);
+		border-start-start-radius: 0;
+		border-end-start-radius: 0;
+	}
 	.nav-label {
 		flex: 1;
 		min-width: 0; /* allow the label to shrink/ellipsis instead of overflowing */

package/dist/components/layouts/NavItem.svelte.d.ts

@@ -2,10 +2,18 @@ import type { Snippet } from 'svelte';
 import type { IconName } from '../atoms/Icon.svelte';
 type BadgeTone = 'neutral' | 'ok' | 'warn' | 'danger' | 'info';
 type $$ComponentProps = {
-    icon: IconName;
+    icon?: IconName;
+    /** Raw 24×24 SVG content, for glyphs outside the registry. Wins over `iconPath` and `icon`. */
+    iconChildren?: Snippet;
+    /** Single `<path d>` for a 24×24 outline glyph. Wins over `icon`. */
+    iconPath?: string;
+    iconSize?: number;
     label: string;
     href?: string;
     active?: boolean;
+    /** 'fill' = accent-tinted pill with a rounded left marker; 'bar' = lighter
+     *  tint with a flat 2px inset accent bar. */
+    activeStyle?: 'fill' | 'bar';
     onclick?: (e: MouseEvent) => void;
     /** Optional trailing count pill (e.g. unread / missing items). When the
      *  item is `active` it adopts the accent fill; otherwise it uses `badgeTone`. */

package/dist/index.d.ts

@@ -1,5 +1,7 @@
+export { artworkGradient, artworkHue, initials } from './artwork';
 export { autoresize } from './autoresize';
 export { copyToClipboard } from './clipboard';
+export { default as Artwork } from './components/atoms/Artwork.svelte';
 export { default as Badge } from './components/atoms/Badge.svelte';
 export { default as Button } from './components/atoms/Button.svelte';
 export { default as Card } from './components/atoms/Card.svelte';

package/dist/index.js

@@ -4,8 +4,10 @@
 // your app root:
 //   import '@dorsk/tsumikit/styles/app.css';
 // then use the components below.
+export { artworkGradient, artworkHue, initials } from './artwork';
 export { autoresize } from './autoresize';
 export { copyToClipboard } from './clipboard';
+export { default as Artwork } from './components/atoms/Artwork.svelte';
 export { default as Badge } from './components/atoms/Badge.svelte';
 export { default as Button } from './components/atoms/Button.svelte';
 export { default as Card } from './components/atoms/Card.svelte';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorsk/tsumikit",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Minimal, dependency-free Svelte 5 + pure-CSS UI kit. Token-driven atoms, molecules & layouts with theming out of the box.",
   "type": "module",
   "license": "MIT",