@svgrid/grid 1.2.34 → 2.0.1

package/dist/virtual.d.ts

@@ -0,0 +1,35 @@
+/**
+ * virtual - a tiny, framework-free fixed-row windowing helper shared by the
+ * selection controls so their option lists scale to tens of thousands of rows
+ * without rendering them all. The renderer measures the viewport + tracks
+ * scrollTop (DOM concerns) and passes them in; this returns the slice to render
+ * plus the top/bottom spacer heights that keep the scrollbar honest.
+ */
+export type VirtualRange = {
+    /** First item index to render (inclusive). */
+    start: number;
+    /** Last item index to render (exclusive). */
+    end: number;
+    /** Spacer height above the rendered slice (px). */
+    padTop: number;
+    /** Spacer height below the rendered slice (px). */
+    padBottom: number;
+    /** Total scrollable height of all rows (px). */
+    totalHeight: number;
+};
+export type VirtualParams = {
+    scrollTop: number;
+    viewportHeight: number;
+    rowHeight: number;
+    count: number;
+    /** Extra rows rendered above/below the viewport to avoid blank flashes. */
+    overscan?: number;
+};
+/** Compute the visible window for a fixed-row-height list (pure). */
+export declare function virtualRange(params: VirtualParams): VirtualRange;
+/**
+ * The scrollTop that brings item `index` fully into a fixed-row viewport,
+ * scrolling the least amount (returns the current scrollTop if already visible).
+ * Pure - the renderer applies it to the element.
+ */
+export declare function scrollToIndex(index: number, scrollTop: number, viewportHeight: number, rowHeight: number): number;

package/dist/virtual.js

@@ -0,0 +1,34 @@
+/** Compute the visible window for a fixed-row-height list (pure). */
+export function virtualRange(params) {
+    const { scrollTop, viewportHeight, rowHeight, count } = params;
+    const overscan = params.overscan ?? 6;
+    const total = Math.max(0, count) * Math.max(0, rowHeight);
+    if (rowHeight <= 0 || count <= 0) {
+        return { start: 0, end: Math.max(0, count), padTop: 0, padBottom: 0, totalHeight: total };
+    }
+    const first = Math.floor(Math.max(0, scrollTop) / rowHeight);
+    const start = Math.max(0, first - overscan);
+    const visible = Math.max(1, Math.ceil(Math.max(0, viewportHeight) / rowHeight));
+    const end = Math.min(count, first + visible + overscan);
+    return {
+        start,
+        end,
+        padTop: start * rowHeight,
+        padBottom: Math.max(0, (count - end) * rowHeight),
+        totalHeight: total,
+    };
+}
+/**
+ * The scrollTop that brings item `index` fully into a fixed-row viewport,
+ * scrolling the least amount (returns the current scrollTop if already visible).
+ * Pure - the renderer applies it to the element.
+ */
+export function scrollToIndex(index, scrollTop, viewportHeight, rowHeight) {
+    const top = index * rowHeight;
+    const bottom = top + rowHeight;
+    if (top < scrollTop)
+        return top;
+    if (bottom > scrollTop + viewportHeight)
+        return bottom - viewportHeight;
+    return scrollTop;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svgrid/grid",
-  "version": "1.2.34",
+  "version": "2.0.1",
   "description": "SvGrid - a headless-first, Svelte 5-native data grid engine and render component.",
   "author": "jQWidgets <boikom@jqwidgets.com>",
   "license": "MIT",

package/src/SvAccordion.svelte

@@ -0,0 +1,109 @@
+<script lang="ts" module>
+  export type { AccordionItem, AccordionExpandMode } from './createAccordion.svelte'
+</script>
+
+<script lang="ts">
+  /**
+   * SvAccordion - a WAI-ARIA accordion (collapsible sections) with single- or
+   * multiple-expand and roving header focus (Up/Down/Home/End). Parity: Smart
+   * `smart-accordion`. Controlled via `expanded` + `onChange`; each panel's body
+   * is rendered through the `panel` snippet (receives the item).
+   *
+   * Behavior (expand state, keyboard, ARIA) lives in the headless `createAccordion`
+   * core; this component is one styled renderer over it.
+   */
+  import type { Snippet } from 'svelte'
+  import { type EditorDir } from './editor-contract'
+  import { createAccordion, type AccordionItem, type AccordionExpandMode } from './createAccordion.svelte'
+
+  type Props = {
+    items: ReadonlyArray<AccordionItem>
+    /** Expanded item ids (controlled). */
+    expanded?: string[]
+    onChange?: (expandedIds: string[]) => void
+    /** 'single' (at most one open) or 'multiple'. Default single. */
+    expandMode?: AccordionExpandMode
+    disabled?: boolean
+    dir?: EditorDir
+    /** Panel body for an item. */
+    panel?: Snippet<[AccordionItem]>
+  }
+
+  let {
+    items,
+    expanded = $bindable([]),
+    onChange,
+    expandMode = 'single',
+    disabled = false,
+    dir,
+    panel,
+  }: Props = $props()
+
+  const resolvedDir = $derived(dir === 'ltr' || dir === 'rtl' ? dir : undefined)
+
+  const acc = createAccordion({
+    items: () => items,
+    expanded: () => expanded,
+    onChange: (ids) => { expanded = ids; onChange?.(ids) },
+    expandMode: () => expandMode,
+    disabled: () => disabled,
+    dir: () => dir,
+  })
+
+  // DOM focus movement is a render concern: follow the core's roving focus header.
+  let rootEl: HTMLDivElement | null = null
+  let lastFocusTick = 0
+  $effect(() => {
+    if (acc.focusTick !== lastFocusTick) {
+      lastFocusTick = acc.focusTick
+      const i = acc.focusIndex
+      queueMicrotask(() => rootEl?.querySelector<HTMLElement>(`[data-idx="${i}"]`)?.focus())
+    }
+  })
+</script>
+
+<div bind:this={rootEl} class="sv-acc" class:is-disabled={disabled} dir={resolvedDir} {...acc.rootProps()}>
+  {#each items as item, i (item.id)}
+    {@const open = acc.isExpanded(item.id)}
+    <div class="sv-acc__item" class:is-open={open}>
+      <h3 class="sv-acc__heading">
+        <button class="sv-acc__header" {...acc.headerProps(i)}>
+          <svg class="sv-acc__chevron" viewBox="0 0 24 24" width="16" height="16" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6" /></svg>
+          <span class="sv-acc__label">{item.label}</span>
+        </button>
+      </h3>
+      {#if open}
+        <div class="sv-acc__panel" {...acc.panelProps(i)}>
+          <div class="sv-acc__body">{#if panel}{@render panel(item)}{/if}</div>
+        </div>
+      {/if}
+    </div>
+  {/each}
+</div>
+
+<style>
+  .sv-acc {
+    --_accent: var(--sg-accent, #2563eb);
+    --_border: var(--sg-border, #e2e8f0);
+    --_radius: var(--sg-radius, 8px);
+    display: flex; flex-direction: column; width: 100%;
+    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--_border); border-radius: var(--_radius); overflow: hidden;
+  }
+  .sv-acc.is-disabled { opacity: 0.6; }
+  .sv-acc__item + .sv-acc__item { border-top: 1px solid var(--_border); }
+  .sv-acc__heading { margin: 0; font: inherit; }
+  .sv-acc__header {
+    display: flex; align-items: center; gap: 8px; width: 100%;
+    padding: 12px 14px; background: none; border: 0; font: inherit; font-size: 14px; font-weight: 600;
+    color: inherit; cursor: pointer; text-align: start;
+  }
+  .sv-acc__header:hover:not(:disabled) { background: var(--sg-row-hover-bg, #f1f5f9); }
+  .sv-acc__header:disabled { opacity: 0.5; cursor: not-allowed; }
+  .sv-acc__header:focus-visible { outline: 2px solid var(--sg-focus-ring, var(--_accent)); outline-offset: -2px; }
+  .sv-acc__chevron { flex: none; color: var(--sg-muted, #64748b); transition: transform 0.16s; }
+  .sv-acc__item.is-open .sv-acc__chevron { transform: rotate(90deg); }
+  .sv-acc[dir='rtl'] .sv-acc__item:not(.is-open) .sv-acc__chevron { transform: scaleX(-1); }
+  .sv-acc__label { flex: 1; }
+  .sv-acc__body { padding: 4px 14px 16px; font-size: 13.5px; line-height: 1.6; color: var(--sg-fg, #0f172a); }
+</style>

package/src/SvAccordion.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Component tests for SvAccordion: single vs multiple expand, ARIA wiring
+ * (aria-expanded / aria-controls / region), and toggle behavior.
+ */
+import { describe, expect, it } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import { createRawSnippet } from 'svelte'
+import SvAccordion from './SvAccordion.svelte'
+
+const items = [
+  { id: 'a', label: 'First' },
+  { id: 'b', label: 'Second' },
+  { id: 'c', label: 'Third' },
+]
+
+// A trivial panel snippet so the body renders.
+const panel = createRawSnippet((item: () => { id: string; label: string }) => ({
+  render: () => `<p>body-${item().id}</p>`,
+}))
+
+function mountAcc(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvAccordion, { target, props: { panel, ...props } as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+describe('SvAccordion', () => {
+  it('renders headers with aria-expanded + aria-controls and shows only the open panel', () => {
+    const { target, destroy } = mountAcc({ items, expanded: ['a'] })
+    try {
+      const headers = [...target.querySelectorAll<HTMLButtonElement>('.sv-acc__header')]
+      expect(headers).toHaveLength(3)
+      expect(headers[0].getAttribute('aria-expanded')).toBe('true')
+      expect(headers[1].getAttribute('aria-expanded')).toBe('false')
+      const region = target.querySelector<HTMLElement>('.sv-acc__panel')!
+      expect(region.getAttribute('role')).toBe('region')
+      expect(region.getAttribute('aria-labelledby')).toBe(headers[0].id)
+      // Only one panel region is rendered (the open one).
+      expect(target.querySelectorAll('.sv-acc__panel')).toHaveLength(1)
+    } finally { destroy() }
+  })
+
+  it('single mode: opening one closes the previous', () => {
+    let got: string[] | undefined
+    const { target, destroy } = mountAcc({ items, expanded: ['a'], expandMode: 'single', onChange: (ids: string[]) => (got = ids) })
+    try {
+      const headers = target.querySelectorAll<HTMLButtonElement>('.sv-acc__header')
+      headers[1].click()
+      flushSync()
+      expect(got).toEqual(['b'])
+    } finally { destroy() }
+  })
+
+  it('multiple mode: toggling accumulates open panels', () => {
+    let got: string[] | undefined
+    const { target, destroy } = mountAcc({ items, expanded: ['a'], expandMode: 'multiple', onChange: (ids: string[]) => (got = ids) })
+    try {
+      const headers = target.querySelectorAll<HTMLButtonElement>('.sv-acc__header')
+      headers[2].click()
+      flushSync()
+      expect(got).toEqual(['a', 'c'])
+    } finally { destroy() }
+  })
+})

package/src/SvAlert.svelte

@@ -0,0 +1,92 @@
+<script lang="ts">
+  /**
+   * SvAlert - an inline, persistent contextual message (info / success / warning
+   * / danger / neutral) with an icon, optional title, dismiss button and trailing
+   * actions. Unlike SvToast (transient, floating), an alert stays in the layout.
+   * Theme-driven via `--sg-*` semantic tokens. Parity: Smart alert / message.
+   */
+  import type { Snippet } from 'svelte'
+
+  type Variant = 'info' | 'success' | 'warning' | 'danger' | 'neutral'
+
+  type Props = {
+    variant?: Variant
+    title?: string
+    /** Show a close (x) button. */
+    dismissible?: boolean
+    onDismiss?: () => void
+    /** Hide the leading status icon. */
+    hideIcon?: boolean
+    /** Softer, borderless tint vs the default bordered card. */
+    soft?: boolean
+    children?: Snippet
+    /** Trailing action buttons / links. */
+    actions?: Snippet
+    /** Custom leading icon (overrides the default glyph). */
+    icon?: Snippet
+  }
+
+  let {
+    variant = 'info',
+    title,
+    dismissible = false,
+    onDismiss,
+    hideIcon = false,
+    soft = false,
+    children,
+    actions,
+    icon,
+  }: Props = $props()
+
+  let open = $state(true)
+  function dismiss() { open = false; onDismiss?.() }
+  const glyph = (v: Variant) =>
+    v === 'success' ? '✓' : v === 'warning' ? '⚠' : v === 'danger' ? '✕' : v === 'neutral' ? '•' : 'ℹ'
+</script>
+
+{#if open}
+  <div
+    class="sv-alert sv-alert--{variant}"
+    class:is-soft={soft}
+    role={variant === 'danger' || variant === 'warning' ? 'alert' : 'status'}
+  >
+    {#if !hideIcon}
+      <span class="sv-alert__icon" aria-hidden="true">{#if icon}{@render icon()}{:else}{glyph(variant)}{/if}</span>
+    {/if}
+    <div class="sv-alert__body">
+      {#if title}<div class="sv-alert__title">{title}</div>{/if}
+      {#if children}<div class="sv-alert__msg">{@render children()}</div>{/if}
+      {#if actions}<div class="sv-alert__actions">{@render actions()}</div>{/if}
+    </div>
+    {#if dismissible}
+      <button type="button" class="sv-alert__x" aria-label="Dismiss" onclick={dismiss}>&times;</button>
+    {/if}
+  </div>
+{/if}
+
+<style>
+  .sv-alert {
+    --_c: var(--sg-info, #0891b2);
+    display: flex; align-items: flex-start; gap: 10px; box-sizing: border-box;
+    padding: 11px 12px; border-radius: 10px; font-size: 13px; line-height: 1.5;
+    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid color-mix(in srgb, var(--_c) 30%, var(--sg-border, #e2e8f0));
+    border-inline-start: 3px solid var(--_c);
+  }
+  .sv-alert.is-soft { border: 0; background: color-mix(in srgb, var(--_c) 12%, transparent); }
+  .sv-alert--info { --_c: var(--sg-info, #0891b2); }
+  .sv-alert--success { --_c: var(--sg-success, #16a34a); }
+  .sv-alert--warning { --_c: var(--sg-warning, #d97706); }
+  .sv-alert--danger { --_c: var(--sg-danger, #dc2626); }
+  .sv-alert--neutral { --_c: var(--sg-muted, #64748b); }
+  .sv-alert__icon { flex: none; width: 18px; height: 18px; display: grid; place-items: center; color: var(--_c); font-weight: 700; }
+  .sv-alert__body { flex: 1; min-width: 0; }
+  .sv-alert__title { font-weight: 650; margin-bottom: 1px; }
+  .sv-alert__msg { color: var(--sg-fg, #0f172a); overflow-wrap: anywhere; }
+  .sv-alert__actions { display: flex; gap: 8px; margin-top: 8px; }
+  .sv-alert__x {
+    flex: none; width: 22px; height: 22px; display: grid; place-items: center; margin: -2px -2px 0 0;
+    background: none; border: 0; color: var(--sg-muted, #64748b); cursor: pointer; border-radius: 5px; font-size: 17px; line-height: 1;
+  }
+  .sv-alert__x:hover { background: var(--sg-row-hover-bg, #f1f5f9); color: var(--sg-fg, #0f172a); }
+</style>

package/src/SvAutoComplete.svelte

@@ -7,24 +7,43 @@
    * One styled renderer over the headless `createAutocomplete` core; only
    * portal/measure render concerns live here.
    */
-  import { anchoredRect, portalToBody, type AnchoredRect } from './popover'
+  import { anchoredRect, portalToBody, popIn, type AnchoredRect } from './popover'
+  import { createDismissableLayer } from './a11y/dismissable'
   import { type ListOption } from './list-option'
+  import SvField from './SvField.svelte'
+  import { nextEditorId, type SvEditorProps } from './editor-contract'
   import { createAutocomplete } from './createAutocomplete.svelte'
 
-  type Props = {
+  type Props = SvEditorProps & {
     value?: string
     onChange?: (value: string) => void
     /** Suggestions - strings or {value,label} (label is shown, value inserted). */
     suggestions?: ReadonlyArray<string | ListOption>
     minChars?: number
     placeholder?: string
-    disabled?: boolean
-    name?: string
-    size?: 'sm' | 'md' | 'lg'
-    ariaLabel?: string
   }
 
-  let { value = '', onChange, suggestions = [], minChars = 1, placeholder, disabled = false, name, size = 'md', ariaLabel }: Props = $props()
+  let {
+    value = '',
+    onChange,
+    suggestions = [],
+    minChars = 1,
+    placeholder,
+    disabled = false,
+    name,
+    size = 'md',
+    ariaLabel,
+    invalid = false,
+    required = false,
+    error,
+    label,
+    hint,
+    dir,
+    id,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-ac')
+  const uid = $derived(id ?? autoId)
 
   let fieldEl = $state<HTMLInputElement | null>(null)
   let panelEl = $state<HTMLDivElement | null>(null)
@@ -38,6 +57,11 @@
     disabled: () => disabled,
     ariaLabel: () => ariaLabel,
     focusInput: () => fieldEl?.focus(),
+    id: () => uid,
+    invalid: () => invalid,
+    required: () => required,
+    error: () => error,
+    hint: () => hint,
   })
 
   function updatePos() {
@@ -50,22 +74,25 @@
     updatePos()
     const rp = () => updatePos()
     window.addEventListener('scroll', rp, true); window.addEventListener('resize', rp)
-    const od = (e: PointerEvent) => { const t = e.target as Node | null; if (t && (fieldEl?.contains(t) || panelEl?.contains(t))) return; ac.close() }
-    document.addEventListener('pointerdown', od, true)
-    return () => { window.removeEventListener('scroll', rp, true); window.removeEventListener('resize', rp); document.removeEventListener('pointerdown', od, true) }
+    const layer = createDismissableLayer({ element: () => [fieldEl, panelEl], onDismiss: () => ac.close(), closeOnEscape: false })
+    layer.activate()
+    return () => { window.removeEventListener('scroll', rp, true); window.removeEventListener('resize', rp); layer.release() }
   })
 </script>
 
-<input
-  bind:this={fieldEl}
-  class="sv-ac sv-ac--{size}"
-  type="text"
-  {placeholder}
-  {...ac.inputProps()}
-/>
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <input
+    bind:this={fieldEl}
+    class="sv-ac sv-ac--{size}"
+    class:is-invalid={invalid}
+    type="text"
+    {placeholder}
+    {...ac.inputProps()}
+  />
+</SvField>
 
 {#if ac.open}
-  <div bind:this={panelEl} class="sv-ddl__panel" use:portalToBody style:position="fixed" style:top={`${rect.top}px`} style:left={`${rect.left}px`} style:min-width={`${rect.width}px`} {...ac.listboxProps()}>
+  <div bind:this={panelEl} class="sv-ddl__panel" use:portalToBody use:popIn={{ up: rect.openUpward }} style:position="fixed" style:top={`${rect.top}px`} style:left={`${rect.left}px`} style:min-width={`${rect.width}px`} {...ac.listboxProps()}>
     {#each ac.filtered as opt, i (opt.value)}
       <!-- svelte-ignore a11y_click_events_have_key_events a11y_interactive_supports_focus -->
       <div class="sv-ddl__opt" class:is-active={ac.isActive(i)} {...ac.optionProps(i)}>{opt.label}</div>
@@ -86,4 +113,6 @@
   .sv-ac--md { height: 34px; font-size: 13px; }
   .sv-ac--lg { height: 40px; font-size: 15px; }
   .sv-ac:focus { border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-ac.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-ac.is-invalid:focus { box-shadow: 0 0 0 2px color-mix(in srgb, var(--sg-danger, #dc2626) 22%, transparent); }
 </style>

package/src/SvAvatar.svelte

@@ -0,0 +1,75 @@
+<script lang="ts">
+  /**
+   * SvAvatar - a user/entity avatar: an image with an initials + colour-hash
+   * fallback (used when there is no `src` or the image fails to load), plus an
+   * optional presence status dot. Parity: Smart avatar.
+   *
+   * ```svelte
+   * <SvAvatar name="Ada Lovelace" src="/ada.jpg" status="online" />
+   * ```
+   */
+  import { avatarInitials, avatarColorHue } from './avatar'
+
+  type Props = {
+    name?: string
+    src?: string
+    alt?: string
+    /** Preset (sm 28 / md 36 / lg 48) or an explicit pixel size. */
+    size?: 'sm' | 'md' | 'lg' | number
+    shape?: 'circle' | 'square'
+    status?: 'online' | 'offline' | 'busy' | 'away'
+    /** Override the hash-derived fallback colour (any CSS colour). */
+    color?: string
+  }
+
+  let { name = '', src, alt, size = 'md', shape = 'circle', status, color }: Props = $props()
+
+  const px = $derived(typeof size === 'number' ? size : size === 'sm' ? 28 : size === 'lg' ? 48 : 36)
+  const initials = $derived(avatarInitials(name))
+  const bg = $derived(color ?? `hsl(${avatarColorHue(name || '?')} 62% 45%)`)
+  // Fall back to initials when the image errors.
+  let broken = $state(false)
+  const showImg = $derived(!!src && !broken)
+</script>
+
+<span
+  class="sv-avatar sv-avatar--{shape}"
+  style:width={`${px}px`}
+  style:height={`${px}px`}
+  style:font-size={`${Math.round(px * 0.4)}px`}
+  style:background={showImg ? undefined : bg}
+  role="img"
+  aria-label={alt ?? (name || 'avatar')}
+  title={name || undefined}
+>
+  {#if showImg}
+    <img class="sv-avatar__img" src={src} alt={alt ?? name} onerror={() => (broken = true)} />
+  {:else if initials}
+    <span class="sv-avatar__initials" aria-hidden="true">{initials}</span>
+  {:else}
+    <svg class="sv-avatar__ph" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M12 12a5 5 0 1 0 0-10 5 5 0 0 0 0 10Zm0 2c-4.4 0-8 2.5-8 5.5V22h16v-2.5C20 16.5 16.4 14 12 14Z" /></svg>
+  {/if}
+  {#if status}<span class="sv-avatar__status is-{status}" aria-hidden="true"></span>{/if}
+</span>
+
+<style>
+  .sv-avatar {
+    position: relative; display: inline-grid; place-items: center; overflow: visible;
+    color: #fff; font-weight: 600; line-height: 1; user-select: none; flex: none;
+    vertical-align: middle;
+  }
+  .sv-avatar--circle { border-radius: 50%; }
+  .sv-avatar--square { border-radius: 22%; }
+  .sv-avatar__img { width: 100%; height: 100%; object-fit: cover; border-radius: inherit; display: block; }
+  .sv-avatar--circle .sv-avatar__img, .sv-avatar--circle { }
+  .sv-avatar__initials { letter-spacing: 0.02em; }
+  .sv-avatar__ph { width: 62%; height: 62%; opacity: 0.9; }
+  .sv-avatar__status {
+    position: absolute; right: -1px; bottom: -1px; width: 28%; height: 28%; min-width: 8px; min-height: 8px;
+    border-radius: 50%; border: 2px solid var(--sg-bg, #fff);
+  }
+  .sv-avatar__status.is-online { background: var(--sg-success, #16a34a); }
+  .sv-avatar__status.is-offline { background: var(--sg-muted, #94a3b8); }
+  .sv-avatar__status.is-busy { background: var(--sg-danger, #dc2626); }
+  .sv-avatar__status.is-away { background: var(--sg-warning, #f59e0b); }
+</style>

package/src/SvAvatarGroup.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+  /**
+   * SvAvatarGroup - overlapping stacked avatars with a "+N" overflow pill, for
+   * "assigned to" / "members" rows. Each entry is a set of SvAvatar props.
+   *
+   * ```svelte
+   * <SvAvatarGroup max={3} avatars={[{ name: 'Ada' }, { name: 'Alan' }, { name: 'Grace' }, { name: 'Ken' }]} />
+   * ```
+   */
+  import SvAvatar from './SvAvatar.svelte'
+
+  type AvatarProps = { name?: string; src?: string; alt?: string; color?: string }
+  type Size = 'sm' | 'md' | 'lg' | number
+
+  type Props = {
+    avatars: ReadonlyArray<AvatarProps>
+    /** Max avatars shown before collapsing to "+N". */
+    max?: number
+    size?: Size
+  }
+
+  let { avatars, max = 4, size = 'md' }: Props = $props()
+
+  const shown = $derived(avatars.slice(0, max))
+  const overflow = $derived(Math.max(0, avatars.length - max))
+  const px = $derived(typeof size === 'number' ? size : size === 'sm' ? 28 : size === 'lg' ? 48 : 36)
+  const overlap = $derived(Math.round(px * 0.28))
+</script>
+
+<div class="sv-avgroup" role="group" style:--ov={`${overlap}px`}>
+  {#each shown as a, i (i)}
+    <span class="sv-avgroup__it" style:z-index={shown.length - i}><SvAvatar {...a} {size} /></span>
+  {/each}
+  {#if overflow}
+    <span class="sv-avgroup__more" style:width={`${px}px`} style:height={`${px}px`} style:font-size={`${Math.round(px * 0.36)}px`}>+{overflow}</span>
+  {/if}
+</div>
+
+<style>
+  .sv-avgroup { display: inline-flex; align-items: center; }
+  .sv-avgroup__it { display: inline-flex; margin-inline-start: calc(-1 * var(--ov, 10px)); border-radius: 50%; box-shadow: 0 0 0 2px var(--sg-bg, #fff); }
+  .sv-avgroup__it:first-child { margin-inline-start: 0; }
+  .sv-avgroup__more {
+    display: grid; place-items: center; margin-inline-start: calc(-1 * var(--ov, 10px)); border-radius: 50%;
+    background: var(--sg-row-hover-bg, #e2e8f0); color: var(--sg-muted, #64748b); font-weight: 650;
+    box-shadow: 0 0 0 2px var(--sg-bg, #fff);
+  }
+</style>

package/src/SvBadge.svelte

@@ -0,0 +1,54 @@
+<script lang="ts">
+  /**
+   * SvBadge - a small status pill / count label. Themed via `--sg-*` tokens with
+   * soft `color-mix` tints so it sits well on light and dark. Parity: Smart badge.
+   *
+   * ```svelte
+   * <SvBadge variant="success">Active</SvBadge>
+   * <SvBadge variant="danger" dot /> 3 failed
+   * ```
+   */
+  import type { Snippet } from 'svelte'
+
+  type Variant = 'neutral' | 'accent' | 'success' | 'warning' | 'danger' | 'info'
+
+  type Props = {
+    variant?: Variant
+    size?: 'sm' | 'md'
+    /** Rounded-pill shape (default) vs a softer rounded rect. */
+    pill?: boolean
+    /** Show a leading status dot instead of / before content. */
+    dot?: boolean
+    children?: Snippet
+  }
+
+  let { variant = 'neutral', size = 'md', pill = true, dot = false, children }: Props = $props()
+</script>
+
+<span class="sv-badge sv-badge--{variant} sv-badge--{size}" class:is-pill={pill} class:has-dot={dot}>
+  {#if dot}<span class="sv-badge__dot" aria-hidden="true"></span>{/if}
+  {@render children?.()}
+</span>
+
+<style>
+  .sv-badge {
+    --_c: var(--sg-muted, #64748b);
+    display: inline-flex; align-items: center; gap: 5px; box-sizing: border-box;
+    font-weight: 600; line-height: 1; white-space: nowrap;
+    color: var(--_c);
+    background: color-mix(in srgb, var(--_c) 14%, transparent);
+    border: 1px solid color-mix(in srgb, var(--_c) 26%, transparent);
+    border-radius: 6px;
+  }
+  .sv-badge.is-pill { border-radius: 999px; }
+  .sv-badge--sm { font-size: 10.5px; padding: 2px 7px; }
+  .sv-badge--md { font-size: 12px; padding: 3px 9px; }
+  .sv-badge__dot { width: 6px; height: 6px; border-radius: 50%; background: var(--_c); }
+
+  .sv-badge--neutral { --_c: var(--sg-muted, #64748b); }
+  .sv-badge--accent { --_c: var(--sg-accent, #2563eb); }
+  .sv-badge--success { --_c: var(--sg-success, #16a34a); }
+  .sv-badge--warning { --_c: var(--sg-warning, #d97706); }
+  .sv-badge--danger { --_c: var(--sg-danger, #dc2626); }
+  .sv-badge--info { --_c: var(--sg-info, #0891b2); }
+</style>