@dorsk/tsumikit 0.57.0 → 0.58.0

package/README.md

@@ -189,9 +189,10 @@ sanctioned escape hatch for everything else.
 
 | component | published properties |
 | --- | --- |
-| `Button` | `--btn-bg`, `--btn-fg`, `--btn-border`, `--btn-size`, `--btn-radius`, `--btn-tone`, `--btn-on`, `--btn-box` |
+| `Button` | `--btn-bg`, `--btn-fg`, `--btn-border`, `--btn-size`, `--btn-radius`, `--btn-tone`, `--btn-on`, `--btn-box`, `--btn-count-bg`, `--btn-count-fg`, `--btn-count-size` |
 | `Badge` | `--badge-bg`, `--badge-fg`, `--badge-border`, `--badge-radius`, `--badge-tone`, `--badge-max-width`, `--badge-fs`, `--badge-fw`, `--badge-min-size` |
 | `Text` | `--txt-fg`, `--txt-size` |
+| `Tabs` | `--tab-max-width` |
 | `Select` | `--select-bg`, `--select-fg`, `--select-border`, `--select-size`, `--select-radius` |
 | `Input` | `--input-bg`, `--input-fg`, `--input-border`, `--input-size`, `--input-radius` |
 | `Textarea` | `--textarea-bg`, `--textarea-fg`, `--textarea-border`, `--textarea-size`, `--textarea-radius` |
@@ -204,7 +205,8 @@ sanctioned escape hatch for everything else.
 | `Fieldset` | `--fieldset-pad`, `--fieldset-border` |
 | `GitRef` | `--git-ref-tone`, `--git-ref-max-width` |
 | `EmptyState` | `--empty-tone` |
-| `Popover` | `--pop-trigger-bg`, `--pop-trigger-fg`, `--pop-trigger-border`, `--pop-trigger-radius`, `--pop-trigger-size`, `--pop-trigger-pad`, `--pop-box` |
+| `Combobox` | `--cb-bg`, `--cb-border`, `--cb-radius`, `--cb-active-bg`, `--cb-min-width`, `--cb-max-height` |
+| `Popover` | `--pop-trigger-bg`, `--pop-trigger-fg`, `--pop-trigger-border`, `--pop-trigger-radius`, `--pop-trigger-size`, `--pop-trigger-pad`, `--pop-box`, `--pop-count-bg`, `--pop-count-fg`, `--pop-count-size` |
 
 `tests/css-custom-property-contract.test.js` reads this table and fails if a
 listed property is not actually read by its component, so the docs cannot drift.
@@ -248,21 +250,40 @@ is used), Textarea, Select (`options` array with per-option `icon`/`emoji`/`hint
 the trigger overlays the selected option's glyph + muted hint on the native control), Switch, Checkbox,
 Slider (`ticks` draws a dot per step for a segmented slider), Progress, Gauge (vertical consumption cell, `variant` continuous/segments,
 threshold tones via `warnAt`/`dangerAt`, `corner` snippet), Artwork (lazy cover image with seeded gradient + initials
-fallback, `aspect`, `status` overlay), Card (`tone` tints the surface for inline banners), Badge
+fallback, `aspect`, `status` overlay), Avatar (grapheme-safe initial or `glyph`, hue hashed from
+`seed`/`name` or a fixed `tone`, `size` xs–lg or px, `shape` circle/square, `decorative`, corner `status`), 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), Divider (standalone
+`icon`, `numeric`, `truncate`, `variant="text"`, `removable`/`onremove` or any
+trailing action via `actionIcon`/`actionLabel`/`onaction`, `removed` mutes and
+strikes the pill for a restorable entry; all tints derive from
+`--badge-tone`), Dot (`ring` dark halo over artwork), Swatch (colour chip:
+`color` any CSS colour, `size` sm/md/lg, `shape` circle/square, `label` → role=img
+else aria-hidden, `interactive` renders a button with `onclick` + `aria-pressed`
+from `selected`), Divider (standalone
 horizontal/vertical hairline, `tone`, `spacing`, optional centred label,
 `decorative` to drop the `separator` role), Link (`tone`, `underline`
 always/hover/none, `align`), Icon (open registry — pass a `children` snippet for
 any custom SVG).
 
-**Molecules:** Field (`grow`), IconButton, SelectButton, Toggle, OptionButton, Modal,
+**Molecules:** Field (`grow`), IconButton, SelectButton, Toggle, OptionButton (`value` +
+`description` secondary text wired via `aria-describedby`, `onfocuschange(value)` on
+focus/hover to drive a preview pane), Modal,
 Popover, Menu (items take a free-form trailing `tag` + `tagTone`, or a `tag` snippet,
-and an `attrs` object for `data-*`/test ids on the row),
-Tabs, RadioGroup (`variant="rows"`: bordered rows, per-option `note`/`description`,
+and an `attrs` object for `data-*`/test ids on the row; a checkable `pressed` item keeps
+its icon leading and shows its check trailing, or uses the leading check slot when it has
+no icon; selecting closes the menu unless `closeOnSelect={false}` or the item sets `keepOpen`),
+Tabs (omit `panel` for a strip-only tablist of document tabs: `closable` + `onclose(id)`
+close through the ✕, Delete and middle-click, per-tab `leading` snippet, `title`,
+trailing `actions` snippet; `--tab-max-width` truncates long labels),
+RadioGroup (per-option `description` in every variant, announced via
+`aria-describedby`; `onfocuschange(value)` fires once per newly focused/hovered option;
+`variant="rows"`: bordered rows, per-option `note`,
 `action(option)` trailing control that never toggles, `below(option)` inline panel),
-Tooltip, Accordion, CopyButton, FileButton,
+Tooltip, Disclosure (single collapsible: `header` snippet, bindable `open` or `open` + `onchange` for
+controlled mode, `chevron` start/end/false, native button with `aria-expanded`/`aria-controls` over a
+`region` panel), Accordion (a stack of Disclosures; items take a `title` string or a `summary` snippet,
+per-item `open`/`onchange`, `multiple=false` keeps one open), CopyButton, FileButton, InputGroup (a field with inset
+leading/trailing controls fused into one bordered unit, see below),
 Dropzone, CodeBlock, Callout, EmptyState, ConfirmModal, Pagination, Toaster,
 ThemePicker (popover grid of 2×2 palette swatches: bg · surface · text · accent per theme),
 EmojiPicker (popover with a searchable EN+FR glyph catalogue, grouped tabs, roving-tabindex grid; pass `groups` to swap the catalogue), FontScalePicker (popover with a stepped slider across the five text sizes), SectionHeader, KeyValue, LoadMore,
@@ -282,7 +303,14 @@ Timestamp (`mode` date/time/datetime/relative/iso/`short-iso` for a locale-indep
 then the leaf ellipsises down to `minLeaf`; `full` skips the fit, `copy` makes it
 a copy-on-click button; candidates via the `workingDirCandidates` helper).
 Fieldset (bordered zone, legend rides the border; `droppable` makes it an HTML5
-drop target with `accepts`/`ondrop`/`dropHint` — keyboard alternative is the consumer's job).
+drop target with `accepts`/`ondrop`/`dropHint` — keyboard alternative is the consumer's job),
+Combobox (suggestion listbox for a field you render as `children` — an Input for
+plain autocomplete or a Textarea for `@`/`#` mentions; the kit sets the field's
+combobox ARIA and `aria-activedescendant`, floats the `role="listbox"` in the top
+layer under the field or under the caret via `anchor="caret"`, and handles
+ArrowUp/Down, Enter/Tab (`selectOn`), Escape and blur; `open`/`index` are
+bindable, `onselect`/`onclose(reason)` report picks; `findTrigger`/`applyTrigger`
+are exported for trigger-char detection and token replacement).
 
 **Organisms:** DataTable (generic `<T>`, typed columns + cell snippets;
 `layout="fixed"` makes column widths authoritative, `Column.truncate` /
@@ -473,6 +501,39 @@ error | done, `onload`, `label`, `loadingLabel`, `errorLabel`, `retryLabel`,
 </SectionHeader>
 ```
 
+### InputGroup
+
+One visual unit: `[leading] field [trailing]` with a single border, radius,
+background and focus ring. The field (`Input` or `Textarea`, optionally wrapped
+by the consumer) keeps its own border and spans the whole group width; the
+`leading`/`trailing` snippets are overlaid inside it and the field pads its
+text past them. This is a hard constraint, not a look: Firefox Android zooms to
+the focused element's rect, so a field laid out beside its buttons zooms the
+page. Adornment widths are measured with a `ResizeObserver` into
+`--ig-leading-w`/`--ig-trailing-w`, so a trailing label that changes
+(`Send (42s)`) never runs under the text.
+
+The adornments sit flush inside the field's padding as ghost/primary controls,
+no dividers: pick a control one step below the group (`size="sm"`/`box="sm"` in
+an `md` group, `box="xs"` in `sm`, `box="lg"` in `lg`). `align="end"` (default)
+pins them to the bottom edge as a textarea grows; `align="center"` is for a
+single-line `Input`. `size` sm/md/lg, `disabled` and `error` flow to the field
+through context (a `size`/`invalid`/`disabled` set on the field still wins).
+`Textarea` keeps `autoresize`, `maxHeight` and `resize="top"` (the grip is
+clipped to the space between the adornments). Tab order is leading → field →
+trailing; the group shows the focus ring around the whole unit.
+
+```svelte
+<InputGroup>
+  {#snippet leading()}<FileButton iconOnly label="Attach" variant="ghost" box="sm" {onfiles} />{/snippet}
+  <Textarea bind:value autoresize rows={1} resize="top" maxHeight="40vh" aria-label="Message" />
+  {#snippet trailing()}<Button variant="primary" size="sm" onclick={send}>Send</Button>{/snippet}
+</InputGroup>
+```
+
+`Composer` is built on it: attachments above, `FileButton` leading, the send
+button trailing, `resize="top"` opt-in.
+
 ### Artwork
 
 `Artwork` is the one cover/thumbnail tile: `src` + `alt` (required) render a
@@ -489,6 +550,45 @@ sm | md | lg | pill, `fit` cover | contain, `hover` for tappable tiles,
 </Artwork>
 ```
 
+### Avatar
+
+`Avatar` is the initials/glyph identity mark for people and accounts. `name`
+gives the initial (first grapheme, so emoji and flags stay whole) and the
+`aria-label`; `glyph` shows an emoji or character instead. The fill hue is
+hashed from `seed` (default `name`) — the same hash as Artwork — or set with
+`hue`; `tone` accent | neutral | none swaps the hash for a fixed palette (`none`
+is for a bare emoji). Hashed fills mix the theme's `--mach-*-sl` pairs with the
+surface and ink tokens at ratios that clear 4.5:1 at every hue on every bundled
+theme. `size` xs | sm | md | lg (1.25–2.5rem) or a pixel number, `shape` circle |
+square, `decorative` drops it from the accessibility tree when the row already
+names the person (otherwise `role="img"`), `status` overlays a Dot on the
+top-right corner, ringed with `--avatar-status-ring` (default `--bg-elevated`).
+`--avatar-bg` / `--avatar-fg` override the colours from outside;
+`avatarInitial(name)` and `avatarHue(seed)` are exported.
+
+```svelte
+<Avatar name={user.name} size={26} decorative />
+<Avatar name="work" glyph="🐙" shape="square" size={16} tone="none" />
+<Avatar name={me} tone="accent" size="sm">
+  {#snippet status()}<Dot status="dead" />{/snippet}
+</Avatar>
+```
+
+### SplitButton
+
+`SplitButton` fuses a primary action with a narrow caret that opens a `Menu`:
+one outer radius, square inner corners, a 1px divider, two tab stops. The
+primary takes `onclick`, `type` (submit inside a form) and `loading`; the caret
+takes `label` (its accessible name), `items`, `placement` and the `Menu`
+panel props (`tag`, `panelClass`, `gap`, `open`, `onopen`, `onclose`).
+`variant` (default | primary | danger), `size` and `control` apply to both
+segments and match `Button` heights; `disabled` turns off the whole control,
+`menuDisabled` only the caret. ArrowDown on the primary opens the menu.
+
+```svelte
+<SplitButton variant="primary" label="Send options" {items} onclick={send}>Send</SplitButton>
+```
+
 ## Container queries
 
 AppShell's `main` and `sidebar` are query containers (`container-name: main` /
@@ -553,6 +653,21 @@ Button and Popover share the same semantic tones. For a confirmed positive
 action, `tone="success"` gives neutral controls a success tint; combine it with
 `variant="primary"` for a filled success action without consumer CSS.
 
+`count` on `Button`, `IconButton` and `Popover` (its trigger) paints a corner
+count pill (unread, selected, queued) on any size, variant or `box`. It hides at
+`0`/`undefined`, displays `99+` past `countMax`, and the exact number joins the
+accessible name (`"Inbox, 120"`) whether that comes from `aria-label`, `label`
+or the button's text. The pill is accent on accent-ink, inverted on `primary`;
+retint one with `--btn-count-bg` / `--btn-count-fg` (`--pop-count-*` on a
+Popover). `formatCount(n, max)` / `hasCount(n)` are exported for a matching
+counter elsewhere.
+
+```svelte
+<IconButton icon="bell" label="Notifications" count={unread} />
+<Button variant="primary" count={selected.length} countMax={999}>Apply</Button>
+<Popover label="Filters" count={active}>{#snippet trigger()}<Icon name="filter" />{/snippet}…</Popover>
+```
+
 ### Square boxes & touch targets
 
 Icon-ish controls share one square scale, `box="xs" | "sm" | "md" | "lg"` =

package/dist/avatar.d.ts

@@ -0,0 +1,6 @@
+/** First grapheme of `name` (so emoji, flags and combining marks stay whole),
+ *  upper-cased. Blank input yields ''. */
+export declare function avatarInitial(name: string): string;
+/** Hue (0–359) for `seed`; the same hash as `artworkHue`, so an Artwork
+ *  fallback and an Avatar for one name agree on their tint. */
+export declare function avatarHue(seed: string): number;

package/dist/avatar.js

@@ -0,0 +1,17 @@
+import { artworkHue } from './artwork';
+/** First grapheme of `name` (so emoji, flags and combining marks stay whole),
+ *  upper-cased. Blank input yields ''. */
+export function avatarInitial(name) {
+    const trimmed = name.trim();
+    if (!trimmed)
+        return '';
+    const first = typeof Intl !== 'undefined' && 'Segmenter' in Intl
+        ? [...new Intl.Segmenter().segment(trimmed)][0]?.segment
+        : [...trimmed][0];
+    return (first ?? '').toUpperCase();
+}
+/** Hue (0–359) for `seed`; the same hash as `artworkHue`, so an Artwork
+ *  fallback and an Avatar for one name agree on their tint. */
+export function avatarHue(seed) {
+    return artworkHue(seed);
+}

package/dist/components/atoms/Avatar.svelte

@@ -0,0 +1,140 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { avatarHue, avatarInitial } from '../../avatar';
+
+	type Own = {
+		name?: string;
+		/** Emoji or character shown instead of the initial. */
+		glyph?: string;
+		/** Seeds the hashed hue. Defaults to `name`. */
+		seed?: string;
+		/** Explicit hue (0–359); overrides `seed`. */
+		hue?: number;
+		/** Fixed palette instead of the hashed hue; `none` drops the fill. */
+		tone?: 'accent' | 'neutral' | 'none';
+		/** Preset box, or a pixel size. */
+		size?: 'xs' | 'sm' | 'md' | 'lg' | number;
+		shape?: 'circle' | 'square';
+		/** `aria-hidden` when the surrounding element already names the person. */
+		decorative?: boolean;
+		/** Overlay pinned to the top-right corner (a Dot). */
+		status?: Snippet;
+		class?: string;
+	};
+	let {
+		name = '',
+		glyph,
+		seed,
+		hue,
+		tone,
+		size = 'md',
+		shape = 'circle',
+		decorative = false,
+		status,
+		class: klass = '',
+		...rest
+	}: Omit<HTMLAttributes<HTMLSpanElement>, keyof Own> & Own = $props();
+
+	const text = $derived(glyph?.trim() || avatarInitial(name) || '?');
+	const hashed = $derived(tone === undefined);
+	const resolvedHue = $derived(hashed ? (hue ?? avatarHue(seed ?? name)) : undefined);
+</script>
+
+<span
+	data-tsu="Avatar"
+	class="avatar {klass}"
+	class:hued={hashed}
+	class:accent={tone === 'accent'}
+	class:neutral={tone === 'neutral'}
+	class:bare={tone === 'none'}
+	class:square={shape === 'square'}
+	class:glyph={glyph !== undefined}
+	class:size-xs={size === 'xs'}
+	class:size-sm={size === 'sm'}
+	class:size-lg={size === 'lg'}
+	style:--avatar-size={typeof size === 'number' ? `${size}px` : undefined}
+	style:--avatar-hue={resolvedHue}
+	role={decorative ? undefined : 'img'}
+	aria-label={decorative ? undefined : name}
+	aria-hidden={decorative ? 'true' : undefined}
+	{...rest}
+>
+	<span class="text" aria-hidden="true">{text}</span>
+	{#if status}
+		<span class="status">{@render status()}</span>
+	{/if}
+</span>
+
+<style>
+	.avatar {
+		--avatar-size: 2rem;
+		position: relative;
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		flex: none;
+		width: var(--avatar-size);
+		height: var(--avatar-size);
+		border-radius: var(--r-pill);
+		font-weight: var(--fw-semibold);
+		font-size: calc(var(--avatar-size) * 0.46);
+		line-height: 1;
+		background: var(--avatar-bg, var(--bg-elevated-2));
+		color: var(--avatar-fg, var(--text-muted));
+		user-select: none;
+		vertical-align: middle;
+	}
+	.size-xs {
+		--avatar-size: 1.25rem;
+	}
+	.size-sm {
+		--avatar-size: 1.5rem;
+	}
+	.size-lg {
+		--avatar-size: 2.5rem;
+	}
+	.square {
+		border-radius: calc(var(--avatar-size) / 4);
+	}
+	/* The fill carries the identity; the initial is theme ink with a hue tint.
+	   These ratios are the ones that clear 4.5:1 at every hue on every bundled
+	   theme (see tests/avatar-contract.test.js). */
+	.hued {
+		background: var(
+			--avatar-bg,
+			color-mix(in srgb, hsl(var(--avatar-hue) var(--mach-bg-sl)) 70%, var(--bg))
+		);
+		color: var(
+			--avatar-fg,
+			color-mix(in srgb, hsl(var(--avatar-hue) var(--mach-fg-sl)) 25%, var(--text))
+		);
+	}
+	.accent {
+		background: var(--avatar-bg, color-mix(in srgb, var(--accent) 18%, transparent));
+		color: var(--avatar-fg, var(--accent));
+	}
+	.bare {
+		background: var(--avatar-bg, none);
+		color: var(--avatar-fg, inherit);
+	}
+	.glyph {
+		font-size: calc(var(--avatar-size) * 0.72);
+		font-weight: var(--fw-normal);
+	}
+	.text {
+		display: block;
+		overflow: hidden;
+		white-space: nowrap;
+	}
+	.status {
+		position: absolute;
+		top: 0;
+		right: 0;
+		display: inline-flex;
+		line-height: 0;
+		border-radius: var(--r-pill);
+		transform: translate(25%, -25%);
+		box-shadow: 0 0 0 2px var(--avatar-status-ring, var(--bg-elevated));
+	}
+</style>

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

@@ -0,0 +1,25 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+type Own = {
+    name?: string;
+    /** Emoji or character shown instead of the initial. */
+    glyph?: string;
+    /** Seeds the hashed hue. Defaults to `name`. */
+    seed?: string;
+    /** Explicit hue (0–359); overrides `seed`. */
+    hue?: number;
+    /** Fixed palette instead of the hashed hue; `none` drops the fill. */
+    tone?: 'accent' | 'neutral' | 'none';
+    /** Preset box, or a pixel size. */
+    size?: 'xs' | 'sm' | 'md' | 'lg' | number;
+    shape?: 'circle' | 'square';
+    /** `aria-hidden` when the surrounding element already names the person. */
+    decorative?: boolean;
+    /** Overlay pinned to the top-right corner (a Dot). */
+    status?: Snippet;
+    class?: string;
+};
+type $$ComponentProps = Omit<HTMLAttributes<HTMLSpanElement>, keyof Own> & Own;
+declare const Avatar: import("svelte").Component<$$ComponentProps, {}, "">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/components/atoms/Badge.svelte

@@ -4,7 +4,9 @@
 	// props rather than separate components:
 	//   • state  → `tone` semantic palette, or `color` for any CSS colour
 	//   • info   → `mono` for paths/ids/code-ish metadata
-	//   • tag    → `removable` renders a dismiss button + fires `onremove`
+	//   • tag    → `removable` renders a dismiss button + fires `onremove`;
+	//              `actionIcon`/`onaction` swap in any other trailing action and
+	//              `removed` mutes + strikes the pill for a "restorable" state
 	// Polymorphic via `as` so it can be a static <span> or an interactive
 	// <button>. Every tinted style derives from the `--badge-tone` custom
 	// property, which is the public hook for consumers who theme by CSS.
@@ -63,6 +65,13 @@
 		icon?: IconName;
 		removable?: boolean;
 		onremove?: (e: MouseEvent) => void;
+		/** Trailing action glyph; renders the action button even without `removable`. */
+		actionIcon?: IconName;
+		/** Accessible name for the action button (defaults to "Remove"). */
+		actionLabel?: string;
+		onaction?: (e: MouseEvent) => void;
+		/** Muted, struck-through look for an entry pending removal. */
+		removed?: boolean;
 		class?: string;
 		children?: Snippet;
 	};
@@ -85,6 +94,10 @@
 		icon,
 		removable = false,
 		onremove,
+		actionIcon,
+		actionLabel,
+		onaction,
+		removed = false,
 		class: klass = '',
 		grow = false,
 		shrink = true,
@@ -94,6 +107,7 @@
 	}: Omit<HTMLAttributes<HTMLElement>, keyof Own> & Own = $props();
 
 	const toneColor = $derived(color ?? (tone === 'neutral' ? undefined : TONE_COLOR[tone]));
+	const hasAction = $derived(removable || actionIcon !== undefined);
 </script>
 
 <svelte:element
@@ -120,6 +134,7 @@
 	class:truncate
 	class:borderless={!border}
 	class:active
+	class:removed
 	class:interactive={as === 'button' || !!href}
 	style:--badge-tone={toneColor}
 	style:--badge-max-width={maxWidth}
@@ -137,14 +152,14 @@
 		{@render children?.()}
 	{/if}
 	{#if href && external}<Icon name="external" />{/if}
-	{#if removable}
+	{#if hasAction}
 		<button
 			type="button"
-			class="remove"
-			aria-label="Remove"
-			onclick={(e) => onremove?.(e)}
+			class="action"
+			aria-label={actionLabel ?? 'Remove'}
+			onclick={(e) => (onaction ?? onremove)?.(e)}
 		>
-			×
+			{#if actionIcon}<Icon name={actionIcon} />{:else}×{/if}
 		</button>
 	{/if}
 </svelte:element>
@@ -253,7 +268,14 @@
 		outline: 2px solid var(--badge-tone, var(--accent));
 		outline-offset: 2px;
 	}
-	.remove {
+	.removed {
+		opacity: 0.55;
+		text-decoration: line-through;
+	}
+	.removed .action {
+		text-decoration: none;
+	}
+	.action {
 		display: inline-flex;
 		align-items: center;
 		justify-content: center;
@@ -268,7 +290,7 @@
 		opacity: 0.6;
 		transition: opacity 0.12s var(--ease);
 	}
-	.remove:hover {
+	.action:hover {
 		opacity: 1;
 	}
 </style>

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

@@ -29,6 +29,13 @@ type Own = {
     icon?: IconName;
     removable?: boolean;
     onremove?: (e: MouseEvent) => void;
+    /** Trailing action glyph; renders the action button even without `removable`. */
+    actionIcon?: IconName;
+    /** Accessible name for the action button (defaults to "Remove"). */
+    actionLabel?: string;
+    onaction?: (e: MouseEvent) => void;
+    /** Muted, struck-through look for an entry pending removal. */
+    removed?: boolean;
     class?: string;
     children?: Snippet;
 };

package/dist/components/atoms/Button.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { formatCount, hasCount } from '../../count';
 	import type { ControlSize } from '../../size';
 	import { canonicalTone, type Tone } from '../../tone';
 	import type { Snippet } from 'svelte';
@@ -56,6 +57,11 @@
 		// Async/busy state: shows a spinner, blocks clicks, sets aria-busy. Stays
 		// disabled-equivalent while true (so a double-submit can't fire).
 		loading?: boolean;
+		// Corner count indicator (unread, selected, pending). Hidden at 0/undefined;
+		// shows `${countMax}+` past the cap while the accessible name carries the
+		// exact number. Tint via `--btn-count-bg` / `--btn-count-fg`.
+		count?: number;
+		countMax?: number;
 		class?: string;
 		children?: Snippet;
 	};
@@ -80,6 +86,8 @@
 		collapseLabel = 'never',
 		hitArea = 'auto',
 		loading = false,
+		count,
+		countMax = 99,
 		type = 'button',
 		disabled = false,
 		title,
@@ -100,13 +108,21 @@
 			: { type, disabled: inactive }
 	);
 
+	const counted = $derived(hasCount(count));
+	const countText = $derived(hasCount(count) ? formatCount(count, countMax) : '');
+	// aria-label replaces the content as the accessible name, so the count is
+	// folded into it; without one the sr-only span below is read after the label.
+	const withCount = (name: string) => (counted ? `${name}, ${count}` : name);
+
 	let el = $state<HTMLElement | null>(null);
 	const explicitName = $derived(rest['aria-label'] ?? rest['aria-labelledby']);
+	const ariaLabel = $derived(rest['aria-label'] ? withCount(rest['aria-label']) : undefined);
 	$effect(() => {
 		if (!el || collapseLabel === 'never' || explicitName) return;
-		const text = Array.from(el.querySelectorAll('[data-label]'), (n) => n.textContent?.trim())
+		const labels = Array.from(el.querySelectorAll('[data-label]'), (n) => n.textContent?.trim())
 			.filter(Boolean)
 			.join(' ');
+		const text = labels && withCount(labels);
 		if (text) el.setAttribute('aria-label', text);
 		else el.removeAttribute('aria-label');
 	});
@@ -118,6 +134,7 @@
 	data-tsu="Button"
 	{...rest}
 	{...elementAttrs}
+	aria-label={ariaLabel}
 	aria-busy={loading || undefined}
 	{title}
 	class="btn {klass}"
@@ -148,10 +165,15 @@
 	class:btn-icon-inline={iconInline}
 	class:hover-danger={hoverDanger}
 	class:loading
+	class:btn-counted={counted}
 	onclick={onclick}
 >
 	{#if loading}<span class="btn-spinner" aria-hidden="true"></span>{/if}
 	{@render children?.()}
+	{#if counted}
+		<span class="btn-count" aria-hidden="true">{countText}</span>
+		<span class="btn-count-sr">, {count}</span>
+	{/if}
 </svelte:element>
 
 <style>
@@ -535,4 +557,53 @@
 			transform: rotate(360deg);
 		}
 	}
+
+	/* Corner count: anchored to the top-right corner and pulled half outside it,
+	   so the button keeps its own box and any size/variant/box carries one. */
+	.btn-counted {
+		position: relative;
+	}
+	.btn-count {
+		position: absolute;
+		top: 0;
+		right: 0;
+		transform: translate(45%, -45%);
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		box-sizing: border-box;
+		min-width: var(--btn-count-size, 1.125rem);
+		height: var(--btn-count-size, 1.125rem);
+		padding: 0 var(--sp-1);
+		border-radius: var(--r-pill);
+		background: var(--btn-count-bg, var(--accent));
+		color: var(--btn-count-fg, var(--text-on-accent));
+		font-size: var(--fs-xs);
+		font-weight: var(--fw-semibold);
+		font-variant-numeric: tabular-nums;
+		line-height: 1;
+		white-space: nowrap;
+		pointer-events: none;
+	}
+	.btn-sm .btn-count,
+	.btn-link .btn-count,
+	.btn-icon-inline .btn-count {
+		--btn-count-size: 1rem;
+		font-size: calc(var(--fs-xs) * 0.85);
+	}
+	/* The accent fill would swallow an accent pill: invert on primary. */
+	.btn-primary .btn-count {
+		background: var(--btn-count-bg, var(--text-on-accent));
+		color: var(--btn-count-fg, var(--accent));
+	}
+	.btn-count-sr {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		margin: -1px;
+		padding: 0;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+	}
 </style>

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

@@ -24,6 +24,8 @@ type ButtonProps = HTMLButtonAttributes & {
     collapseLabel?: 'never' | 'mobile' | 'container';
     hitArea?: 'auto' | 'compact';
     loading?: boolean;
+    count?: number;
+    countMax?: number;
     class?: string;
     children?: Snippet;
 };