@spaethtech/svelte-ui 0.12.0 → 0.13.0

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 export { default as Alert } from "./components/Alert.svelte";
 export { default as Banner } from "./components/Banner.svelte";
 export { default as Badge } from "./components/Badge/Badge.svelte";
+export { Chip } from "./components/Chip/index.js";
+export { Avatar, AvatarGroup } from "./components/Avatar/index.js";
+export type { AvatarShape, AvatarStatus, AvatarItem } from "./components/Avatar/index.js";
 export { default as Button } from "./components/Button.svelte";
 export { default as ButtonDropdown } from "./components/ButtonDropdown.svelte";
 export { default as Card } from "./components/Card.svelte";
@@ -45,14 +48,18 @@ export { default as Toggle } from "./components/Toggle.svelte";
 export { default as Radio } from "./components/Radio.svelte";
 export { default as FieldGroup } from "./components/FieldGroup.svelte";
 export { default as Grid } from "./components/Grid.svelte";
+export { Divider } from "./components/Divider/index.js";
 export type { Columns, Gap } from "./components/field-group.js";
 export { default as Disclosure } from "./components/Disclosure.svelte";
 export { default as Accordion } from "./components/Accordion.svelte";
 export { default as SideBarMenu } from "./components/SideBarMenu/SideBarMenu.svelte";
 export type { SideBarMenuItem, SideBarMenuBadge, SideBarMenuBadgeVariant, SideBarMenuApi, SideBarMenuMode, SideBarMenuActiveRule, } from "./components/SideBarMenu/SideBarMenu.svelte";
+export { Breadcrumbs } from "./components/Breadcrumbs/index.js";
+export type { BreadcrumbItem } from "./components/Breadcrumbs/index.js";
 export { default as TabStrip } from "./components/TabStrip/TabStrip.svelte";
 export type { TabDefinition } from "./components/TabStrip/TabStrip.svelte";
 export { default as DataTable } from "./components/DataTable.svelte";
+export { Pagination } from "./components/Pagination/index.js";
 export { default as Query } from "./components/Query.svelte";
 export { anchored, computePlacement, resolveBoundary } from "./positioning/anchored.js";
 export type { Side, Align, Boundary, PlaceOptions, Placement, AnchoredParams, } from "./positioning/anchored.js";

package/dist/index.js

@@ -2,6 +2,8 @@
 export { default as Alert } from "./components/Alert.svelte";
 export { default as Banner } from "./components/Banner.svelte";
 export { default as Badge } from "./components/Badge/Badge.svelte";
+export { Chip } from "./components/Chip/index.js";
+export { Avatar, AvatarGroup } from "./components/Avatar/index.js";
 export { default as Button } from "./components/Button.svelte";
 export { default as ButtonDropdown } from "./components/ButtonDropdown.svelte";
 export { default as Card } from "./components/Card.svelte";
@@ -48,13 +50,16 @@ export { default as Toggle } from "./components/Toggle.svelte";
 export { default as Radio } from "./components/Radio.svelte";
 export { default as FieldGroup } from "./components/FieldGroup.svelte";
 export { default as Grid } from "./components/Grid.svelte";
+export { Divider } from "./components/Divider/index.js";
 export { default as Disclosure } from "./components/Disclosure.svelte";
 export { default as Accordion } from "./components/Accordion.svelte";
 // Navigation Components
 export { default as SideBarMenu } from "./components/SideBarMenu/SideBarMenu.svelte";
+export { Breadcrumbs } from "./components/Breadcrumbs/index.js";
 export { default as TabStrip } from "./components/TabStrip/TabStrip.svelte";
 // Data table (pairs with the `svelte-ui/data` headless layer)
 export { default as DataTable } from "./components/DataTable.svelte";
+export { Pagination } from "./components/Pagination/index.js";
 export { default as Query } from "./components/Query.svelte";
 // Positioning engine (shared by Popup and tooltips)
 export { anchored, computePlacement, resolveBoundary } from "./positioning/anchored.js";

package/dist/positioning/anchored.d.ts

@@ -21,6 +21,10 @@ export interface PlaceOptions {
     margin?: number;
     /** Resolve the boundary rect the placement must stay within. Default the viewport. */
     boundary?: Boundary;
+    /** When >0, round the cross-axis *shift* (the amount the box is shoved to stay in the boundary) UP
+     *  to a whole multiple of this many px. Lets a row-based menu shove by whole rows so it stays in
+     *  phase with an adjacent list. Default 0 (free-px shift). */
+    snap?: number;
 }
 export interface Placement {
     x: number;

package/dist/positioning/anchored.js

@@ -25,7 +25,7 @@ export function resolveBoundary(boundary = "viewport") {
  * vertically per `align`. Flips to the opposite side, then scans, when the preferred side won't fit.
  */
 export function computePlacement(anchor, size, opts = {}) {
-    const { side = "bottom", align = "start", offset = 4, margin = 8 } = opts;
+    const { side = "bottom", align = "start", offset = 4, margin = 8, snap = 0 } = opts;
     const b = resolveBoundary(opts.boundary);
     const { width: fw, height: fh } = size;
     const fits = (s) => {
@@ -75,9 +75,24 @@ export function computePlacement(anchor, size, opts = {}) {
                     ? anchor.bottom - fh
                     : anchor.top;
     }
-    // Clamp into the boundary (shift), so the box never spills past the edges.
-    x = Math.min(Math.max(x, b.left + margin), b.right - margin - fw);
-    y = Math.min(Math.max(y, b.top + margin), b.bottom - margin - fh);
+    // Clamp into the boundary (shift), so the box never spills past the edges. The CROSS axis (the one
+    // perpendicular to the chosen side) can `snap` its shift to whole steps; the main axis never snaps.
+    const clampSnap = (v, min, max) => {
+        const c = Math.min(Math.max(v, min), max);
+        if (snap > 0 && c !== v) {
+            // Shoved by (c - v); round the magnitude UP to a whole step, keep direction, re-clamp.
+            const shoved = v + Math.sign(c - v) * Math.ceil(Math.abs(c - v) / snap) * snap;
+            return Math.min(Math.max(shoved, min), max);
+        }
+        return c;
+    };
+    const crossVertical = chosen === "left" || chosen === "right";
+    x = crossVertical
+        ? Math.min(Math.max(x, b.left + margin), b.right - margin - fw)
+        : clampSnap(x, b.left + margin, b.right - margin - fw);
+    y = crossVertical
+        ? clampSnap(y, b.top + margin, b.bottom - margin - fh)
+        : Math.min(Math.max(y, b.top + margin), b.bottom - margin - fh);
     return { x, y, side: chosen, maxHeight };
 }
 /**

package/docs/components.md

@@ -182,6 +182,16 @@ per-child prop). Works with any content. Uniform cells only (for variable widths
 - **Props**: `columns` (`number | { base, md, … }`, 1–6, default `1`), `gap` (`number | { x, y }`,
   default `4`), `class`, `children`. Shares `gridColsClass`/`gapClass` with `FieldGroup`.
 
+### Divider
+
+A thin separating rule.
+
+- **Location**: `src/lib/components/Divider/Divider.svelte`
+- **Props**: `orientation` (`horizontal`/`vertical`), `label`/`children` (inline label, horizontal),
+  `labelAlign` (`start`/`center`/`end`), `class`. No `variant`/`size`.
+- **Accessibility**: `role="separator"` + `aria-orientation` (plain horizontal uses `<hr>`)
+- **Theming**: line = `--ui-border-color`; label muted. Vertical stretches to the row via `self-stretch`.
+
 ### Disclosure
 
 A single expand/collapse section — a `<Button>` header (title + rotating chevron) over a content
@@ -260,6 +270,19 @@ snaps to canonical on blur.
 
 ## Navigation
 
+### Breadcrumbs
+
+Navigation trail (root → current); composes `Button` (links) + `Menu` (overflow).
+
+- **Location**: `src/lib/components/Breadcrumbs/Breadcrumbs.svelte`
+- **Axes**: `size`
+- **Props**: `items` (`BreadcrumbItem[]` = `{ label, href?, onclick?, icon? }`; last = current page),
+  `separator` (Snippet | string, default chevron), `maxItems` (collapse middle → `⋯` Menu; needs ≥3),
+  `size`, `class`
+- **Accessibility**: `<nav aria-label="Breadcrumb">` + `<ol>`; current crumb `aria-current="page"` and
+  not a link; ellipsis button has `aria-haspopup`/`aria-expanded`
+- **Composition**: link crumbs are `Button variant="ghost"`; overflow crumbs live in a `Menu`
+
 ### TabStrip
 
 A horizontal tab bar (renders as a `tablist` of buttons, or a `navigation` of links when any tab has
@@ -301,6 +324,19 @@ dialog (operators, casts, dynamic `now()` dates, and a worked examples table). T
 - **Note**: URL sync is intentionally not built in — observe `dataset.applied` and sync yourself.
   Built on `Input` + `Button` + `Popup` + `Dialog`.
 
+### Pagination
+
+Standalone page navigator — the reusable extraction of `DataTable`'s footer pager.
+
+- **Location**: `src/lib/components/Pagination/Pagination.svelte`
+- **Axes**: `variant` (active page fill), `size`
+- **Props**: `page` (bindable), `total`, `perPage` (bindable), `perPageOptions` (→ rows-per-page
+  `Select`), `siblingCount`/`boundaryCount`, `showEdges` (first/last), `showTotal`, `disabled`, `class`
+- **Behavior**: numbered buttons with ellipsis for long ranges (active = filled, rest `ghost`);
+  prev/next/first/last disable at the ends; choosing `perPage` resets to page 1; `page` clamps to range
+- **Accessibility**: `<nav aria-label="Pagination">`; active page `aria-current="page"`
+- **Composition**: `Button` + `Select` only (no raw `<button>`)
+
 ## Overlays
 
 ### Dialog
@@ -390,6 +426,20 @@ Shared placement engine — a Svelte action plus `computePlacement` / `resolveBo
 
 ## Display / Theme
 
+### Avatar / AvatarGroup
+
+Person/entity likeness with a graceful fallback chain; `AvatarGroup` stacks with a `+N` overflow.
+
+- **Location**: `src/lib/components/Avatar/Avatar.svelte`, `AvatarGroup.svelte`
+- **Axes**: `size` (`sm`/`md`/`lg` = 32/40/48px), `variant` (fallback fill)
+- **Avatar props**: `src`, `name` (initials + alt), `alt`, `icon` (snippet), `shape`
+  (`circle`/`square`), `status` (`online`/`offline`/`busy`/`away`), `class`. Fallback order:
+  `src` (until load error) → `name` initials → `icon` → default glyph.
+- **AvatarGroup props**: `items` (`AvatarItem[]` = `{ src?, name?, alt?, variant?, icon? }`), `max`
+  (→ `+N` chip), `size`/`shape`/`variant` defaults, or `children` (hand-authored, no overflow), `class`
+- **Theming**: fallback fill = variant token @20% + strong token text; status dot = semantic token;
+  overlap ring = `--ui-color-background`. No per-component tokens.
+
 ### Spinner
 
 Indeterminate loading ring — the primitive `Button`'s `loading` state and the loading family build on.
@@ -426,6 +476,20 @@ Colour-neutral content placeholder for loading states.
 - **Theming**: neutral text-tint base + CSS shimmer; corners use `--ui-border-radius`. Compose several
   to sketch a card/list row.
 
+### Chip
+
+Interactive pill — the interactive counterpart to `Badge` (display-only).
+
+- **Location**: `src/lib/components/Chip/Chip.svelte`
+- **Axes**: `variant`, `size` (`sm`/`md`/`lg` = 24/32/40px)
+- **Props**: `text`/`children`, `icon` (leading), `selected` (toggle → filled), `removable` +
+  `onremove` (× ; also Backspace/Delete when focused), `onclick` (→ `role="button"` + `aria-pressed`),
+  `href` (→ `<a>`), `disabled`, `rounded` (pill, default), `class`
+- **HTML**: root is a `span`/`a` (never a `<button>`) so a removable chip's × can be a real nested
+  `<button>` without invalid nesting
+- **Theming**: selected = variant token fill + white text; unselected = `--ui-tint-soft` fill +
+  `--ui-tint-border` border + `--ui-tint-strong` text (same vocabulary as `Badge`). No per-component tokens.
+
 ### Badge
 
 Status indicator / label.

package/docs/usage.md

@@ -631,6 +631,115 @@ An edge-anchored panel that slides in — same modal mechanics as `Dialog`, pinn
 </Badge>
 ```
 
+### Divider
+
+A thin separating rule — horizontal (optionally labelled) or vertical (toolbars).
+
+```svelte
+<script>
+  import { Divider } from "@spaethtech/svelte-ui";
+</script>
+
+<Divider />
+<Divider label="OR" />
+<Divider label="Recent" labelAlign="start" />
+
+<!-- Vertical, inside a flex row -->
+<div class="flex items-center gap-3 h-8">
+  <span>Edit</span>
+  <Divider orientation="vertical" />
+  <span>Share</span>
+</div>
+```
+
+### Pagination
+
+A standalone page navigator (numbered buttons + ellipsis, prev/next, optional per-page + total).
+
+```svelte
+<script>
+  import { Pagination } from "@spaethtech/svelte-ui";
+  let page = $state(1);
+  let perPage = $state(10);
+</script>
+
+<Pagination bind:page bind:perPage total={247} perPageOptions={[10, 25, 50, 100]} showTotal />
+
+<!-- Compact: numbers only, with first/last controls -->
+<Pagination bind:page total={200} showEdges />
+```
+
+### Breadcrumbs
+
+A navigation trail; the last item is the current page. `maxItems` collapses the middle into a `⋯` menu.
+
+```svelte
+<script>
+  import { Breadcrumbs } from "@spaethtech/svelte-ui";
+
+  const trail = [
+    { label: "Home", href: "/" },
+    { label: "Components", href: "/components" },
+    { label: "Breadcrumbs" }, // last = current page (not a link)
+  ];
+</script>
+
+<Breadcrumbs items={trail} />
+
+<!-- Collapse a long trail; custom separator -->
+<Breadcrumbs items={trail} maxItems={4} separator="/" />
+```
+
+### Chip
+
+An interactive pill — filter/choice tokens, removable tags, clickable labels.
+
+```svelte
+<script>
+  import { Chip } from "@spaethtech/svelte-ui";
+
+  const FILTERS = ["All", "Active", "Archived"];
+  let active = $state("Active");
+
+  let tags = $state(["design", "svelte", "ui"]);
+  const remove = (t) => (tags = tags.filter((x) => x !== t));
+</script>
+
+<!-- Filter / choice: selected fills with the variant (consumer owns which is on) -->
+{#each FILTERS as f}
+  <Chip text={f} selected={active === f} variant="primary" onclick={() => (active = f)} />
+{/each}
+
+<!-- Removable tags: the × fires onremove (Backspace/Delete on a focused chip also removes) -->
+{#each tags as t (t)}
+  <Chip text={t} removable onremove={() => remove(t)} />
+{/each}
+```
+
+### Avatar
+
+A likeness with a fallback chain (image → initials → icon → glyph). `AvatarGroup` stacks with `+N`.
+
+```svelte
+<script>
+  import { Avatar, AvatarGroup } from "@spaethtech/svelte-ui";
+
+  const team = [
+    { name: "Jane Doe", src: "/1.jpg" },
+    { name: "Ravi Patel", src: "/2.jpg" },
+    { name: "Mia Chen" }, // no src → initials "MC"
+  ];
+</script>
+
+<Avatar src="/jane.jpg" name="Jane Doe" />
+<Avatar name="Jane Doe" variant="primary" /> <!-- initials fallback -->
+<Avatar />                                    <!-- default glyph -->
+<Avatar name="Jane Doe" status="online" />    <!-- status dot -->
+
+<!-- Overlapped group; extras beyond max collapse into a +N chip -->
+<AvatarGroup items={team} max={4} />
+```
+
 ### TextArea
 
 ```svelte

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"