@marianmeres/stuic 3.167.0 → 3.169.0

package/dist/components/Pagination/Pagination.svelte.d.ts

@@ -0,0 +1,69 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { Snippet } from "svelte";
+import type { PagingCalcResult } from "@marianmeres/paging-store";
+import type { TranslateFn } from "../../types.js";
+import type { ButtonSize } from "../Button/Button.svelte";
+export type PaginationVariant = "compact" | "numbers";
+export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /**
+     * Paging calculation result from `@marianmeres/paging-store` — the exact shape
+     * `DataTable` consumes, so both can be fed from the same store or `calculatePaging`
+     * call. Takes precedence over the `total`/`limit`/`offset` convenience props.
+     */
+    paging?: PagingCalcResult;
+    /** Convenience alternative to `paging`: total number of items in the dataset. */
+    total?: number;
+    /** Convenience alternative to `paging`: items per page (default 10). */
+    limit?: number;
+    /** Convenience alternative to `paging`: current offset (default 0). */
+    offset?: number;
+    /**
+     * Callback when the user navigates to a different page. First argument is the new
+     * offset (`DataTable`'s `onPageChange` signature), second is the 1-based target page.
+     */
+    onPageChange?: (offset: number, page: number) => void;
+    /**
+     * `"compact"` (default): prev / "Page X of Y" / next — the `DataTable` pager.
+     * `"numbers"`: windowed page-number buttons with ellipsis gaps.
+     */
+    variant?: PaginationVariant;
+    /** Numbers variant: pages always shown around the current page (default 1). */
+    siblingCount?: number;
+    /** Numbers variant: pages always shown at the start and at the end (default 1). */
+    boundaryCount?: number;
+    /** Render first/last jump buttons (default false). */
+    showFirstLast?: boolean;
+    /**
+     * Render the "Page X of Y" info. Defaults per variant: `true` for compact (between
+     * prev/next), `false` for numbers (after the buttons when enabled).
+     */
+    showInfo?: boolean;
+    /**
+     * Render nothing when there is at most one page (default true — the `DataTable`
+     * rule: one page of results needs no pager). Set `false` to keep it visible.
+     */
+    hideSinglePage?: boolean;
+    /** Disable all controls (e.g. while a page of data is loading). */
+    disabled?: boolean;
+    /** Size preset passed to the inner Buttons (default "sm", as in `DataTable`). */
+    size?: ButtonSize;
+    /** i18n translate function (see `createPaginationT`). */
+    t?: TranslateFn;
+    /** Override the "Page X of Y" info content. */
+    renderInfo?: Snippet<[PagingCalcResult]>;
+    /** Skip all default styling (inner Buttons keep their own Button styling) */
+    unstyled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Class for every inner button */
+    classButton?: string;
+    /** Extra class for the current-page button (numbers variant) */
+    classButtonCurrent?: string;
+    /** Class for the "Page X of Y" info */
+    classInfo?: string;
+    /** Bindable element reference */
+    el?: HTMLElement;
+}
+declare const Pagination: import("svelte").Component<Props, {}, "el">;
+type Pagination = ReturnType<typeof Pagination>;
+export default Pagination;

package/dist/components/Pagination/README.md

@@ -0,0 +1,152 @@
+# Pagination
+
+Standalone pagination control for lists, search results, and custom views. Two
+variants: `compact` — prev / "Page X of Y" / next, which _is_ the pager `DataTable`
+renders internally — and `numbers` — windowed page-number buttons with ellipsis gaps
+(the classic `1 … 4 5 6 … 20`).
+
+Consumes the same `PagingCalcResult` from
+[`@marianmeres/paging-store`](https://github.com/marianmeres/paging-store) that
+`DataTable` does, so one paging store (or one `calculatePaging` call) can feed both.
+For quick standalone use, `total`/`limit`/`offset` props compute the paging
+internally.
+
+## Props
+
+| Prop                 | Type                     | Default     | Description                                                                           |
+| -------------------- | ------------------------ | ----------- | ------------------------------------------------------------------------------------- |
+| `paging`             | `PagingCalcResult`       | -           | Paging metadata (same shape `DataTable` consumes); wins over `total`/`limit`/`offset` |
+| `total`              | `number`                 | -           | Convenience alternative to `paging`: total item count                                 |
+| `limit`              | `number`                 | `10`        | Convenience alternative to `paging`: page size                                        |
+| `offset`             | `number`                 | `0`         | Convenience alternative to `paging`: current offset                                   |
+| `onPageChange`       | `(offset, page) => void` | -           | Navigation callback: new offset (`DataTable`-compatible first arg) + 1-based page     |
+| `variant`            | `"compact" \| "numbers"` | `"compact"` | Prev/info/next, or windowed page-number buttons                                       |
+| `siblingCount`       | `number`                 | `1`         | Numbers variant: pages always shown around the current page                           |
+| `boundaryCount`      | `number`                 | `1`         | Numbers variant: pages always shown at the start and end                              |
+| `showFirstLast`      | `boolean`                | `false`     | Render first/last jump buttons (« »)                                                  |
+| `showInfo`           | `boolean`                | per variant | "Page X of Y" info; defaults `true` for compact, `false` for numbers                  |
+| `hideSinglePage`     | `boolean`                | `true`      | Render nothing when there is at most one page (the `DataTable` rule)                  |
+| `disabled`           | `boolean`                | `false`     | Disable all controls (e.g. while loading)                                             |
+| `size`               | `ButtonSize`             | `"sm"`      | Size preset of the inner Buttons                                                      |
+| `t`                  | `TranslateFn`            | English     | i18n translate function (see below)                                                   |
+| `unstyled`           | `boolean`                | `false`     | Skip pagination styling (inner Buttons keep their own Button styling)                 |
+| `class`              | `string`                 | -           | Additional CSS classes (merged via twMerge)                                           |
+| `classButton`        | `string`                 | -           | Class for every inner button                                                          |
+| `classButtonCurrent` | `string`                 | -           | Extra class for the current-page button (numbers variant)                             |
+| `classInfo`          | `string`                 | -           | Class for the "Page X of Y" info                                                      |
+| `el`                 | `HTMLElement`            | -           | Element reference (bindable)                                                          |
+
+## Snippet Props
+
+| Snippet      | Description                                                              |
+| ------------ | ------------------------------------------------------------------------ |
+| `renderInfo` | Override the "Page X of Y" info content; receives the `PagingCalcResult` |
+
+## Usage
+
+### Basic (compact)
+
+```svelte
+<script lang="ts">
+	import { Pagination } from "@marianmeres/stuic";
+
+	let offset = $state(0);
+</script>
+
+<Pagination total={137} limit={10} {offset} onPageChange={(o) => (offset = o)} />
+```
+
+### With a paging store (shared with DataTable)
+
+The `paging` prop takes the exact object `DataTable` consumes — hide the table's
+built-in pager and drive both from one store:
+
+```svelte
+<script lang="ts">
+	import { DataTable, Pagination } from "@marianmeres/stuic";
+	import { createPagingStore } from "@marianmeres/paging-store";
+
+	const paging = createPagingStore({ total: 137, limit: 10, offset: 0 });
+	const onPageChange = (offset: number) => paging.update({ offset });
+</script>
+
+<DataTable {columns} {data} paging={$paging} showPager={false} />
+<Pagination paging={$paging} {onPageChange} variant="numbers" />
+```
+
+### Numbers variant
+
+```svelte
+<Pagination variant="numbers" total={200} {offset} onPageChange={(o) => (offset = o)} />
+
+<!-- wider window, first/last jumps -->
+<Pagination
+	variant="numbers"
+	siblingCount={2}
+	boundaryCount={2}
+	showFirstLast
+	total={200}
+	{offset}
+	onPageChange={(o) => (offset = o)}
+/>
+```
+
+### i18n
+
+Built-in English; bundled Slovak (`PAGINATION_MESSAGES_SK`) is opt-in. The
+`previous_page`, `next_page` and `page_x_of_y` keys are identical to `DataTable`'s,
+so one merged catalog (and one `t`) can serve both components.
+
+```svelte
+<script lang="ts">
+	import {
+		Pagination,
+		createPaginationT,
+		PAGINATION_MESSAGES_SK,
+	} from "@marianmeres/stuic";
+	const t = createPaginationT(PAGINATION_MESSAGES_SK);
+</script>
+
+<Pagination {paging} {onPageChange} {t} />
+```
+
+### Custom info
+
+```svelte
+<Pagination {paging} {onPageChange}>
+	{#snippet renderInfo(p)}
+		{p.offset + 1}–{Math.min(p.offset + p.limit, p.total)} of {p.total}
+	{/snippet}
+</Pagination>
+```
+
+### Single page
+
+By default nothing renders when there is at most one page (same rule as
+`DataTable`'s internal pager). Keep it visible with `hideSinglePage={false}`.
+
+## Accessibility
+
+- Renders a `<nav aria-label="Pagination">` landmark (label localized via `t`).
+- Every button carries a localized `aria-label`; the current page button (numbers
+  variant) is marked `aria-current="page"`.
+
+## Exports
+
+Besides the component: `paginationRange(currentPage, pageCount, { siblingCount, boundaryCount })`
+— the pure windowing helper behind the numbers variant, usable for fully custom pagers.
+
+## CSS Variables
+
+| Variable                              | Default                          | Description                                        |
+| ------------------------------------- | -------------------------------- | -------------------------------------------------- |
+| `--stuic-pagination-gap`              | `0.5rem`                         | Gap between controls                               |
+| `--stuic-pagination-button-min-width` | `--stuic-button-min-height-sm`   | Min button width (keeps number buttons square-ish) |
+| `--stuic-pagination-info-font-size`   | `--text-sm`                      | Info font size                                     |
+| `--stuic-pagination-info-text`        | `--stuic-color-muted-foreground` | Info color                                         |
+| `--stuic-pagination-ellipsis-text`    | `--stuic-color-muted-foreground` | Ellipsis color                                     |
+
+## Data Attributes
+
+- `data-variant` - `"compact" | "numbers"` (on the root `<nav>`)
+- `data-current` - `"true"` on the current-page button (numbers variant)

package/dist/components/Pagination/i18n-sk.d.ts

@@ -0,0 +1,17 @@
+import type { PaginationMessages } from "./i18n.js";
+/**
+ * Slovak message catalog for `Pagination`. Opt-in — English stays the built-in default,
+ * and this module is only pulled into a bundle when it is actually imported (the
+ * component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Pagination, createPaginationT, PAGINATION_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createPaginationT(PAGINATION_MESSAGES_SK);
+ * </script>
+ *
+ * <Pagination {paging} {onPageChange} {t} />
+ * ```
+ */
+export declare const PAGINATION_MESSAGES_SK: PaginationMessages;

package/dist/components/Pagination/i18n-sk.js

@@ -0,0 +1,24 @@
+/**
+ * Slovak message catalog for `Pagination`. Opt-in — English stays the built-in default,
+ * and this module is only pulled into a bundle when it is actually imported (the
+ * component itself never references it).
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Pagination, createPaginationT, PAGINATION_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createPaginationT(PAGINATION_MESSAGES_SK);
+ * </script>
+ *
+ * <Pagination {paging} {onPageChange} {t} />
+ * ```
+ */
+export const PAGINATION_MESSAGES_SK = {
+    previous_page: "Späť",
+    next_page: "Ďalej",
+    first_page: "Prvá strana",
+    last_page: "Posledná strana",
+    page_x_of_y: "Strana {page} z {pageCount}",
+    go_to_page_x: "Prejsť na stranu {page}",
+    pagination: "Stránkovanie",
+};

package/dist/components/Pagination/i18n.d.ts

@@ -0,0 +1,41 @@
+import type { TranslateFn } from "../../types.js";
+/**
+ * The built-in (English) message catalog of `Pagination`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * The `previous_page`, `next_page` and `page_x_of_y` keys are intentionally identical
+ * to `DataTable`'s, so one merged catalog (and one `t`) can serve both components.
+ *
+ * Placeholders are single-brace (`{page}`, `{pageCount}`, ...).
+ */
+export declare const PAGINATION_MESSAGES_EN: {
+    previous_page: string;
+    next_page: string;
+    first_page: string;
+    last_page: string;
+    page_x_of_y: string;
+    go_to_page_x: string;
+    pagination: string;
+};
+/** Every message key `Pagination` may look up. */
+export type PaginationMessageKey = keyof typeof PAGINATION_MESSAGES_EN;
+/** A (possibly partial) catalog for one locale. */
+export type PaginationMessages = Record<PaginationMessageKey, string>;
+/**
+ * Builds the `t` prop of `Pagination` from a message catalog. Unknown or untranslated
+ * keys fall back to `fallbackMessages` (English by default), so a catalog may safely be
+ * partial and never renders a raw key.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Pagination, createPaginationT, PAGINATION_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createPaginationT(PAGINATION_MESSAGES_SK);
+ * </script>
+ *
+ * <Pagination {paging} {onPageChange} {t} />
+ * ```
+ */
+export declare function createPaginationT(messages: Partial<PaginationMessages> | Record<string, string>, fallbackMessages?: Partial<PaginationMessages> | Record<string, string>): TranslateFn;
+/** The component's built-in English `t`. */
+export declare const t_default: TranslateFn;

package/dist/components/Pagination/i18n.js

@@ -0,0 +1,49 @@
+import { isPlainObject } from "../../utils/is-plain-object.js";
+import { replaceMap } from "../../utils/replace-map.js";
+/**
+ * The built-in (English) message catalog of `Pagination`. Also the fallback of every
+ * other bundled locale, so a locale missing a key still renders text.
+ *
+ * The `previous_page`, `next_page` and `page_x_of_y` keys are intentionally identical
+ * to `DataTable`'s, so one merged catalog (and one `t`) can serve both components.
+ *
+ * Placeholders are single-brace (`{page}`, `{pageCount}`, ...).
+ */
+export const PAGINATION_MESSAGES_EN = {
+    previous_page: "Prev",
+    next_page: "Next",
+    first_page: "First page",
+    last_page: "Last page",
+    page_x_of_y: "Page {page} of {pageCount}",
+    go_to_page_x: "Go to page {page}",
+    pagination: "Pagination",
+};
+/**
+ * Builds the `t` prop of `Pagination` from a message catalog. Unknown or untranslated
+ * keys fall back to `fallbackMessages` (English by default), so a catalog may safely be
+ * partial and never renders a raw key.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { Pagination, createPaginationT, PAGINATION_MESSAGES_SK } from "@marianmeres/stuic";
+ *   const t = createPaginationT(PAGINATION_MESSAGES_SK);
+ * </script>
+ *
+ * <Pagination {paging} {onPageChange} {t} />
+ * ```
+ */
+export function createPaginationT(messages, fallbackMessages = PAGINATION_MESSAGES_EN) {
+    return (k, values = null, fallback = "") => {
+        const out = messages[k] ??
+            fallbackMessages[k] ??
+            (typeof fallback === "string" ? fallback : k);
+        return isPlainObject(values)
+            ? replaceMap(out, values, {
+                preSearchKeyTransform: (k) => `{${k}}`,
+            })
+            : out;
+    };
+}
+/** The component's built-in English `t`. */
+export const t_default = createPaginationT(PAGINATION_MESSAGES_EN);

package/dist/components/Pagination/index.css

@@ -0,0 +1,50 @@
+/* ============================================================================
+   PAGINATION COMPONENT TOKENS
+   Override globally: :root { --stuic-pagination-gap: 1rem; }
+   Override locally:  <Pagination style="--stuic-pagination-button-min-width: 2rem;">
+   ============================================================================ */
+
+/* prettier-ignore */
+:root {
+	--stuic-pagination-gap: 0.5rem;
+
+	/* Keeps single-character buttons («, ‹, page numbers) square-ish and aligned.
+	   Sized to the `size="sm"` Button height. Text buttons (Prev/Next) simply exceed it. */
+	--stuic-pagination-button-min-width: var(--stuic-button-min-height-sm, 2.75rem);
+
+	/* "Page X of Y" info */
+	--stuic-pagination-info-font-size: var(--text-sm);
+	--stuic-pagination-info-text: var(--stuic-color-muted-foreground);
+
+	/* Ellipsis gap (numbers variant) */
+	--stuic-pagination-ellipsis-text: var(--stuic-color-muted-foreground);
+}
+
+@layer components {
+	.stuic-pagination {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		flex-wrap: wrap;
+		gap: var(--stuic-pagination-gap);
+	}
+
+	.stuic-pagination-button {
+		min-width: var(--stuic-pagination-button-min-width);
+	}
+
+	.stuic-pagination-info {
+		font-size: var(--stuic-pagination-info-font-size);
+		color: var(--stuic-pagination-info-text);
+		white-space: nowrap;
+	}
+
+	.stuic-pagination-ellipsis {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		min-width: var(--stuic-pagination-button-min-width);
+		color: var(--stuic-pagination-ellipsis-text);
+		user-select: none;
+	}
+}

package/dist/components/Pagination/index.d.ts

@@ -0,0 +1,4 @@
+export { default as Pagination, type Props as PaginationProps, type PaginationVariant, } from "./Pagination.svelte";
+export { paginationRange, type PaginationRangeItem, type PaginationRangeOptions, } from "./pagination-range.js";
+export { createPaginationT, PAGINATION_MESSAGES_EN, type PaginationMessageKey, type PaginationMessages, } from "./i18n.js";
+export { PAGINATION_MESSAGES_SK } from "./i18n-sk.js";

package/dist/components/Pagination/index.js

@@ -0,0 +1,4 @@
+export { default as Pagination, } from "./Pagination.svelte";
+export { paginationRange, } from "./pagination-range.js";
+export { createPaginationT, PAGINATION_MESSAGES_EN, } from "./i18n.js";
+export { PAGINATION_MESSAGES_SK } from "./i18n-sk.js";

package/dist/components/Pagination/pagination-range.d.ts

@@ -0,0 +1,21 @@
+/** One rendered slot of the "numbers" variant: a page number or an ellipsis gap. */
+export type PaginationRangeItem = number | "ellipsis";
+export interface PaginationRangeOptions {
+    /** How many pages to always show around the current page (default 1). */
+    siblingCount?: number;
+    /** How many pages to always show at the start and at the end (default 1). */
+    boundaryCount?: number;
+}
+/**
+ * Computes the windowed page list of the "numbers" variant: boundary pages at both
+ * ends, siblings around the current page, and `"ellipsis"` tokens for the collapsed
+ * gaps. The window is stable — for a given `pageCount` and options, every
+ * `currentPage` yields the same number of slots (no layout jumping while paging).
+ *
+ * @example
+ * ```ts
+ * paginationRange(5, 10); // [1, "ellipsis", 4, 5, 6, "ellipsis", 10]
+ * paginationRange(1, 5);  // [1, 2, 3, 4, 5]
+ * ```
+ */
+export declare function paginationRange(currentPage: number, pageCount: number, options?: PaginationRangeOptions): PaginationRangeItem[];

package/dist/components/Pagination/pagination-range.js

@@ -0,0 +1,41 @@
+/**
+ * Computes the windowed page list of the "numbers" variant: boundary pages at both
+ * ends, siblings around the current page, and `"ellipsis"` tokens for the collapsed
+ * gaps. The window is stable — for a given `pageCount` and options, every
+ * `currentPage` yields the same number of slots (no layout jumping while paging).
+ *
+ * @example
+ * ```ts
+ * paginationRange(5, 10); // [1, "ellipsis", 4, 5, 6, "ellipsis", 10]
+ * paginationRange(1, 5);  // [1, 2, 3, 4, 5]
+ * ```
+ */
+export function paginationRange(currentPage, pageCount, options = {}) {
+    const siblingCount = Math.max(0, Math.floor(options.siblingCount ?? 1));
+    const boundaryCount = Math.max(0, Math.floor(options.boundaryCount ?? 1));
+    if (!Number.isFinite(pageCount) || pageCount <= 0)
+        return [];
+    const page = Math.min(Math.max(1, Math.floor(currentPage) || 1), pageCount);
+    const range = (start, end) => Array.from({ length: end - start + 1 }, (_, i) => start + i);
+    const startPages = range(1, Math.min(boundaryCount, pageCount));
+    const endPages = range(Math.max(pageCount - boundaryCount + 1, boundaryCount + 1), pageCount);
+    const siblingsStart = Math.max(Math.min(page - siblingCount, pageCount - boundaryCount - siblingCount * 2 - 1), boundaryCount + 2);
+    const siblingsEnd = Math.min(Math.max(page + siblingCount, boundaryCount + siblingCount * 2 + 2), endPages.length > 0 ? endPages[0] - 2 : pageCount - 1);
+    return [
+        ...startPages,
+        // start gap: ellipsis, the single page it would hide, or nothing
+        ...(siblingsStart > boundaryCount + 2
+            ? ["ellipsis"]
+            : boundaryCount + 1 < pageCount - boundaryCount
+                ? [boundaryCount + 1]
+                : []),
+        ...range(siblingsStart, siblingsEnd),
+        // end gap: ellipsis, the single page it would hide, or nothing
+        ...(siblingsEnd < pageCount - boundaryCount - 1
+            ? ["ellipsis"]
+            : pageCount - boundaryCount > boundaryCount
+                ? [pageCount - boundaryCount]
+                : []),
+        ...endPages,
+    ];
+}

package/dist/components/Pill/Pill.svelte

@@ -42,6 +42,8 @@
 		dismissible?: boolean;
 		/** Called when X is clicked. Stops propagation so parent onclick is unaffected. */
 		ondismiss?: (e: MouseEvent) => void;
+		/** Accessible name of the built-in X dismiss button */
+		dismissLabel?: string;
 		/** Status dot rendered before content (uses current intent color) */
 		dot?: boolean;
 		/** Content rendered before children */
@@ -76,6 +78,7 @@
 		disabled,
 		dismissible = false,
 		ondismiss,
+		dismissLabel = "Dismiss",
 		dot = false,
 		contentBefore,
 		contentAfter,
@@ -109,11 +112,14 @@
 	<button
 		type="button"
 		class="stuic-pill-dismiss"
-		aria-label="Dismiss"
+		aria-label={dismissLabel}
 		onclick={handleDismiss}
 		{disabled}
 	>
-		<X strokeWidth={2} />
+		<!-- The icon box is sized in CSS (tokens); the X itself just fills it. -->
+		<span class="stuic-pill-dismiss-icon" aria-hidden="true">
+			<X class="size-full" strokeWidth={2.5} />
+		</span>
 	</button>
 {/snippet}
 

package/dist/components/Pill/Pill.svelte.d.ts

@@ -35,6 +35,8 @@ export interface Props extends Omit<HTMLAttributes<HTMLElement>, "children"> {
     dismissible?: boolean;
     /** Called when X is clicked. Stops propagation so parent onclick is unaffected. */
     ondismiss?: (e: MouseEvent) => void;
+    /** Accessible name of the built-in X dismiss button */
+    dismissLabel?: string;
     /** Status dot rendered before content (uses current intent color) */
     dot?: boolean;
     /** Content rendered before children */

package/dist/components/Pill/README.md

@@ -4,27 +4,28 @@ A small rounded inline element for tags, badges, status indicators, and filter c
 
 ## Props
 
-| Prop            | Type                                                               | Default  | Description                                                           |
-| --------------- | ------------------------------------------------------------------ | -------- | --------------------------------------------------------------------- |
-| `intent`        | `"primary" \| "accent" \| "destructive" \| "warning" \| "success"` | -        | Semantic color intent                                                 |
-| `variant`       | `"solid" \| "outline" \| "ghost" \| "soft" \| "link"`              | `"soft"` | Visual variant (how colors are applied)                               |
-| `size`          | `"sm" \| "md" \| "lg"`                                             | `"md"`   | Pill size                                                             |
-| `muted`         | `boolean`                                                          | `false`  | Reduce emphasis (lower opacity)                                       |
-| `active`        | `boolean`                                                          | `false`  | Selected/active state (filter-chip behavior)                          |
-| `roundedFull`   | `boolean`                                                          | `true`   | Fully rounded corners (9999px). Set `false` to use the element radius |
-| `block`         | `boolean`                                                          | `false`  | Render as block-level flex (full width). `inline-flex` by default     |
-| `unstyled`      | `boolean`                                                          | `false`  | Skip all default styling                                              |
-| `href`          | `string`                                                           | -        | Render as `<a>` with this URL                                         |
-| `target`        | `string`                                                           | -        | Link target (only when `href` is set)                                 |
-| `onclick`       | `(e: MouseEvent) => void`                                          | -        | Render as `<button>` with this handler (when no `href`)               |
-| `disabled`      | `boolean`                                                          | -        | Disabled state (interactive variants only)                            |
-| `dismissible`   | `boolean`                                                          | `false`  | Show built-in X dismiss button                                        |
-| `ondismiss`     | `(e: MouseEvent) => void`                                          | -        | Called when X is clicked. Stops propagation                           |
-| `dot`           | `boolean`                                                          | `false`  | Status dot rendered before content                                    |
-| `contentBefore` | `THC`                                                              | -        | Content rendered before children                                      |
-| `contentAfter`  | `THC`                                                              | -        | Content rendered after children                                       |
-| `el`            | `HTMLElement`                                                      | -        | Element reference (bindable)                                          |
-| `class`         | `string`                                                           | -        | Additional CSS classes                                                |
+| Prop            | Type                                                               | Default     | Description                                                           |
+| --------------- | ------------------------------------------------------------------ | ----------- | --------------------------------------------------------------------- |
+| `intent`        | `"primary" \| "accent" \| "destructive" \| "warning" \| "success"` | -           | Semantic color intent                                                 |
+| `variant`       | `"solid" \| "outline" \| "ghost" \| "soft" \| "link"`              | `"soft"`    | Visual variant (how colors are applied)                               |
+| `size`          | `"sm" \| "md" \| "lg"`                                             | `"md"`      | Pill size                                                             |
+| `muted`         | `boolean`                                                          | `false`     | Reduce emphasis (lower opacity)                                       |
+| `active`        | `boolean`                                                          | `false`     | Selected/active state (filter-chip behavior)                          |
+| `roundedFull`   | `boolean`                                                          | `true`      | Fully rounded corners (9999px). Set `false` to use the element radius |
+| `block`         | `boolean`                                                          | `false`     | Render as block-level flex (full width). `inline-flex` by default     |
+| `unstyled`      | `boolean`                                                          | `false`     | Skip all default styling                                              |
+| `href`          | `string`                                                           | -           | Render as `<a>` with this URL                                         |
+| `target`        | `string`                                                           | -           | Link target (only when `href` is set)                                 |
+| `onclick`       | `(e: MouseEvent) => void`                                          | -           | Render as `<button>` with this handler (when no `href`)               |
+| `disabled`      | `boolean`                                                          | -           | Disabled state (interactive variants only)                            |
+| `dismissible`   | `boolean`                                                          | `false`     | Show built-in X dismiss button                                        |
+| `ondismiss`     | `(e: MouseEvent) => void`                                          | -           | Called when X is clicked. Stops propagation                           |
+| `dismissLabel`  | `string`                                                           | `"Dismiss"` | Accessible name of the X dismiss button                               |
+| `dot`           | `boolean`                                                          | `false`     | Status dot rendered before content                                    |
+| `contentBefore` | `THC`                                                              | -           | Content rendered before children                                      |
+| `contentAfter`  | `THC`                                                              | -           | Content rendered after children                                       |
+| `el`            | `HTMLElement`                                                      | -           | Element reference (bindable)                                          |
+| `class`         | `string`                                                           | -           | Additional CSS classes                                                |
 
 ## Element Resolution
 
@@ -172,6 +173,15 @@ A small rounded inline element for tags, badges, status indicators, and filter c
 | `--stuic-pill-gap`          | `0.375rem`             | Gap between dot/before/children/after/dismiss           |
 | `--stuic-pill-dot-size`     | `0.5rem`               | Status dot diameter                                     |
 
+### Dismiss Button Tokens
+
+| Variable                         | Default                                             | Description                                                         |
+| -------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------- |
+| `--stuic-pill-dismiss-min-size`  | `1.5rem`                                            | Touch-target floor for the X button (its square never gets smaller) |
+| `--stuic-pill-dismiss-icon-size` | `1.125em`                                           | Size of the X glyph box (relative to the pill font size)            |
+| `--stuic-pill-dismiss-bg-hover`  | `color-mix(in srgb, currentColor 12%, transparent)` | Hover background of the whole X square                              |
+| `--stuic-pill-dismiss-bg-active` | `color-mix(in srgb, currentColor 20%, transparent)` | Pressed background of the whole X square                            |
+
 ### Size Tokens
 
 Each size (sm, md, lg) has corresponding tokens:
@@ -181,7 +191,10 @@ Each size (sm, md, lg) has corresponding tokens:
 - `--stuic-pill-font-size-{size}`
 - `--stuic-pill-min-height-{size}`
 
-Dismissible pills override `padding-y` to `0` (the X button defines the height).
+Dismissible pills override `padding-y` and `padding-inline-end` to `0`: the X button is a
+full-height square (side = the pill's `min-height`, floored at `--stuic-pill-dismiss-min-size`)
+sitting flush with the pill's end edge, and the whole square is the hover/press surface — not just
+the glyph. Its corners inherit the pill radius, so on rounded pills the hover surface is the end cap.
 
 ### Intent Color Tokens