contain-css-svelte 1.1.20 → 1.2.0

package/dist/overlays/Dialog.svelte

@@ -1,8 +1,21 @@
 <script lang="ts">import CircleButton from "../controls/CircleButton.svelte";
-import { copyCSSVariables, injectVars } from "../util";
-let { open = true, modal = true, dismissible = false, children, onClose, onclose: oncloseProp = null, ...restProps } = $props();
+import { copyCSSVariables, splitProps } from "../util";
+import { COLOR_VARS, PADDING_VARS, RADIUS_VARS, TYPOGRAPHY_CONTAINER_VARS, } from "../styleProps";
+let { open = true, modal = true, dismissible = false, children, onClose, onclose: oncloseProp = null, class: className, ...restProps } = $props();
 let onclose = $derived(oncloseProp || onClose);
-const style = $derived(injectVars(restProps, "dialog", []));
+/* The <section> is the variable carrier that copyCSSVariables reads through,
+   so it takes the style while the <dialog> takes the attributes -- a
+   caller's `aria-*` and `data-*` belong on the dialog itself. */
+/* The shorthands this component's own CSS backs, one group per mixin
+   it includes. The Props type is derived from this same array, so what
+   the component accepts and what it emits cannot drift apart. */
+const DIALOG_VARS = [
+    ...COLOR_VARS,
+    ...PADDING_VARS,
+    ...RADIUS_VARS,
+    ...TYPOGRAPHY_CONTAINER_VARS,
+];
+const el = $derived(splitProps(restProps, "dialog", DIALOG_VARS));
 // Handle backdrop click to close modal (click outside behavior)
 // Clicks on the dialog element itself (the backdrop) close the dialog
 function handleBackdropClick(event) {
@@ -52,9 +65,9 @@ let dialogElement;
 let ref;
 </script>
 
-<section {style}>
+<section style={el.style}>
   <div class="variable-placeholder" bind:this={ref}></div>
-  <dialog bind:this={dialogElement} {onclose} {...restProps}>
+  <dialog bind:this={dialogElement} {onclose} class={className} {...el.attrs}>
     <div class="close-bar">
       <div class="close-button">
         <CircleButton onclick={onclose}>&times;</CircleButton>

package/dist/overlays/Dialog.svelte.d.ts

@@ -1,12 +1,14 @@
+import { type StyleProps } from "../styleProps";
 import type { Snippet } from "svelte";
-type PropsType = {
+import type { HTMLDialogAttributes } from "svelte/elements";
+import type { ContainProps } from "../types";
+declare const Dialog: import("svelte").Component<ContainProps<HTMLDialogAttributes, {
     open?: boolean;
     modal?: boolean;
     dismissible?: boolean;
     children?: Snippet;
     onclose?: (() => void) | null;
     onClose?: (() => void) | null;
-} & Record<string, unknown>;
-declare const Dialog: import("svelte").Component<PropsType, {}, "">;
+}, StyleProps<readonly ["bg", "fg", "padding", "borderRadius", "fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "textAlign", "textTransform", "textDecoration", "fontVariant", "lineWidth"]>>, {}, "">;
 type Dialog = ReturnType<typeof Dialog>;
 export default Dialog;

package/dist/overlays/Tooltip.svelte

@@ -1,8 +1,24 @@
 <script lang="ts">import { onDestroy, tick } from "svelte";
+import { elementProps } from "../util";
+import { COLOR_VARS, PADDING_VARS, RADIUS_VARS, TYPOGRAPHY_CONTAINER_VARS, } from "../styleProps";
 let tooltipDiv = $state();
 let targetDiv = $state();
 let tooltipMeasurementDiv = $state();
-let { tooltipText = "", vertical = "bottom", horizontal = "right", children, tooltip, block = false, } = $props();
+let { tooltipText = "", vertical = "bottom", horizontal = "right", children, tooltip, block = false, class: className, ...restProps } = $props();
+/* The wrapper is the element a caller is pointing at -- the tooltip itself
+   is a popover the component owns and positions. */
+/* The shorthands this component's own CSS backs, one group per mixin
+   it includes. The Props type is derived from this same array, so what
+   the component accepts and what it emits cannot drift apart. */
+const TOOLTIP_VARS = [
+    ...COLOR_VARS,
+    ...PADDING_VARS,
+    ...RADIUS_VARS,
+    ...TYPOGRAPHY_CONTAINER_VARS,
+];
+/* The variables land on the wrapper and reach the popover by inheritance:
+   the tooltip is a descendant of it, and custom properties inherit. */
+const el = $derived(elementProps(restProps, "tooltip", TOOLTIP_VARS));
 // svelte-ignore state_referenced_locally
 let renderedVertical = $state(vertical);
 // svelte-ignore state_referenced_locally
@@ -206,11 +222,12 @@ async function showPopover() {
 {#if block}
   <!-- svelte-ignore a11y_no_static_element_interactions -->
   <div
-    class="tooltip-wrapper"
+    class={["tooltip-wrapper", className]}
     onmouseenter={() => showPopover()}
     onmouseleave={() => hidePopover()}
     onfocusin={() => showPopover()}
     onfocusout={() => hidePopover()}
+    {...el}
   >
     <div class="tooltip-target" bind:this={targetDiv}>
       {@render children?.()}
@@ -241,11 +258,12 @@ async function showPopover() {
 {:else}
   <!-- svelte-ignore a11y_no_static_element_interactions -->
   <span
-    class="tooltip-wrapper"
+    class={["tooltip-wrapper", className]}
     onmouseenter={() => showPopover()}
     onmouseleave={() => hidePopover()}
     onfocusin={() => showPopover()}
     onfocusout={() => hidePopover()}
+    {...el}
   >
     <span class="tooltip-target" bind:this={targetDiv}>
       {@render children?.()}

package/dist/overlays/Tooltip.svelte.d.ts

@@ -1,11 +1,13 @@
-interface Props {
+import type { HTMLAttributes } from "svelte/elements";
+import type { ContainProps } from "../types";
+import { type StyleProps } from "../styleProps";
+declare const Tooltip: import("svelte").Component<ContainProps<HTMLAttributes<HTMLElement>, {
     tooltipText?: string;
     vertical?: string;
     horizontal?: string;
     children?: import("svelte").Snippet;
     tooltip?: import("svelte").Snippet;
     block?: boolean;
-}
-declare const Tooltip: import("svelte").Component<Props, {}, "">;
+}, StyleProps<readonly ["bg", "fg", "padding", "borderRadius", "fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "textAlign", "textTransform", "textDecoration", "fontVariant", "lineWidth"]>>, {}, "">;
 type Tooltip = ReturnType<typeof Tooltip>;
 export default Tooltip;

package/dist/styleProps.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The style-prop shorthands, grouped to mirror the SCSS mixins that make them
+ * readable.
+ *
+ * The problem this solves: which shorthands a component accepted used to be a
+ * hand-maintained list in each component, drifting from the mixins its CSS
+ * actually included. Tag exposed `fontSize` while the other 23 components
+ * whose CSS includes a typography mixin exposed none of it -- `--button-font-
+ * weight` resolved perfectly well, there was just no prop for it. In the other
+ * direction, FormItem injected three variables no stylesheet read at all.
+ *
+ * So each group below names one mixin, and a component's prop list is the
+ * union of the groups for the mixins its own CSS includes. "Which shorthands
+ * does this component take" stops being a decision and becomes a consequence.
+ *
+ * The prop types are derived from these same arrays via `StyleProps<>`, so the
+ * type and the runtime list cannot disagree -- adding a name to the array is
+ * what adds the prop.
+ *
+ * A shorthand is only safe when the element the component renders has no HTML
+ * attribute of that name: `ContainProps` resolves the clash by dropping the
+ * attribute, which is right for a deprecated or meaningless one and wrong for
+ * `<progress max>` or `<option label>`. That is why the size group is applied
+ * per component rather than being folded into the others, and why Progress's
+ * accessible-name prop is `progressLabel`.
+ */
+/** Every style prop takes a CSS value, or null/undefined to leave it unset. */
+export type StyleProps<T extends readonly string[]> = {
+    [K in T[number]]?: string | null;
+};
+/** `@include color-props(<prefix>, ...)` */
+export declare const COLOR_VARS: readonly ["bg", "fg"];
+/** `@include padding-props(...)`, and the box-props family that includes it */
+export declare const PADDING_VARS: readonly ["padding"];
+/** The border-radius the box-props family sets alongside padding */
+export declare const RADIUS_VARS: readonly ["borderRadius"];
+/** `@include margin-props(<prefix>, ...)` */
+export declare const MARGIN_VARS: readonly ["marginBlock", "marginInline"];
+/** `@include gap-props(<prefix>, ...)` */
+export declare const GAP_VARS: readonly ["gap"];
+/**
+ * `@include typography-props(...)` and its `-bare` / `-bold` variants.
+ *
+ * `fontSize` was the only one of these ever exposed as a prop, and only on
+ * Tag. The rest resolved in CSS the whole time.
+ */
+export declare const TYPOGRAPHY_VARS: readonly ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "textAlign", "textTransform", "textDecoration", "fontVariant"];
+/**
+ * `@include typography-container-props(...)`, which is typography-props plus
+ * the readable measure it imposes on prose children.
+ */
+export declare const TYPOGRAPHY_CONTAINER_VARS: readonly ["fontFamily", "fontSize", "fontWeight", "lineHeight", "letterSpacing", "textAlign", "textTransform", "textDecoration", "fontVariant", "lineWidth"];
+/**
+ * `@include box-size-props(<prefix>, ...)`.
+ *
+ * Deliberately NOT part of any other group: `width` and `height` are real HTML
+ * attributes on `<input>`, `<img>`, `<canvas>` and `<iframe>`, so a component
+ * rendering one of those must not shadow them. Applied per component.
+ */
+export declare const SIZE_VARS: readonly ["width", "minWidth", "maxWidth", "height", "minHeight", "maxHeight"];
+export type ColorStyleProps = StyleProps<typeof COLOR_VARS>;
+export type PaddingStyleProps = StyleProps<typeof PADDING_VARS>;
+export type RadiusStyleProps = StyleProps<typeof RADIUS_VARS>;
+export type GapStyleProps = StyleProps<typeof GAP_VARS>;
+export type TypographyStyleProps = StyleProps<typeof TYPOGRAPHY_VARS>;
+export type TypographyContainerStyleProps = StyleProps<typeof TYPOGRAPHY_CONTAINER_VARS>;
+export type SizeStyleProps = StyleProps<typeof SIZE_VARS>;

package/dist/styleProps.js

@@ -0,0 +1,76 @@
+/**
+ * The style-prop shorthands, grouped to mirror the SCSS mixins that make them
+ * readable.
+ *
+ * The problem this solves: which shorthands a component accepted used to be a
+ * hand-maintained list in each component, drifting from the mixins its CSS
+ * actually included. Tag exposed `fontSize` while the other 23 components
+ * whose CSS includes a typography mixin exposed none of it -- `--button-font-
+ * weight` resolved perfectly well, there was just no prop for it. In the other
+ * direction, FormItem injected three variables no stylesheet read at all.
+ *
+ * So each group below names one mixin, and a component's prop list is the
+ * union of the groups for the mixins its own CSS includes. "Which shorthands
+ * does this component take" stops being a decision and becomes a consequence.
+ *
+ * The prop types are derived from these same arrays via `StyleProps<>`, so the
+ * type and the runtime list cannot disagree -- adding a name to the array is
+ * what adds the prop.
+ *
+ * A shorthand is only safe when the element the component renders has no HTML
+ * attribute of that name: `ContainProps` resolves the clash by dropping the
+ * attribute, which is right for a deprecated or meaningless one and wrong for
+ * `<progress max>` or `<option label>`. That is why the size group is applied
+ * per component rather than being folded into the others, and why Progress's
+ * accessible-name prop is `progressLabel`.
+ */
+/** `@include color-props(<prefix>, ...)` */
+export const COLOR_VARS = ["bg", "fg"];
+/** `@include padding-props(...)`, and the box-props family that includes it */
+export const PADDING_VARS = ["padding"];
+/** The border-radius the box-props family sets alongside padding */
+export const RADIUS_VARS = ["borderRadius"];
+/** `@include margin-props(<prefix>, ...)` */
+export const MARGIN_VARS = ["marginBlock", "marginInline"];
+/** `@include gap-props(<prefix>, ...)` */
+export const GAP_VARS = ["gap"];
+/**
+ * `@include typography-props(...)` and its `-bare` / `-bold` variants.
+ *
+ * `fontSize` was the only one of these ever exposed as a prop, and only on
+ * Tag. The rest resolved in CSS the whole time.
+ */
+export const TYPOGRAPHY_VARS = [
+    "fontFamily",
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+    "letterSpacing",
+    "textAlign",
+    "textTransform",
+    "textDecoration",
+    "fontVariant",
+];
+/**
+ * `@include typography-container-props(...)`, which is typography-props plus
+ * the readable measure it imposes on prose children.
+ */
+export const TYPOGRAPHY_CONTAINER_VARS = [
+    ...TYPOGRAPHY_VARS,
+    "lineWidth",
+];
+/**
+ * `@include box-size-props(<prefix>, ...)`.
+ *
+ * Deliberately NOT part of any other group: `width` and `height` are real HTML
+ * attributes on `<input>`, `<img>`, `<canvas>` and `<iframe>`, so a component
+ * rendering one of those must not shadow them. Applied per component.
+ */
+export const SIZE_VARS = [
+    "width",
+    "minWidth",
+    "maxWidth",
+    "height",
+    "minHeight",
+    "maxHeight",
+];

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Common CSS variable props that can be passed to components.
- * These are converted to CSS custom properties via injectVars().
+ * These are converted to CSS custom properties via elementProps().
  */
 /** Base style props supported by most components */
 export interface BaseStyleProps {
@@ -88,3 +88,42 @@ export interface DropdownMenuStyleProps extends BaseStyleProps {
     triggerFg?: string | null;
     triggerPadding?: string | null;
 }
+/**
+ * Props that let a caller set CSS custom properties directly on a component.
+ *
+ * NOTE: writing `<Tag --tag-bg="red">` in a template does NOT go through this
+ * type -- Svelte intercepts `--*` attributes on components itself and renders
+ * `<svelte-css-wrapper style="display: contents; --tag-bg: red;">` around the
+ * component. This type covers the remaining path, an object spread
+ * (`<Tag {...{"--tag-bg": "red"}}>`), which Svelte cannot detect statically and
+ * therefore passes through as an ordinary prop.
+ */
+export type CssVarProps = {
+    [key: `--${string}`]: string | number | null | undefined;
+};
+/**
+ * The standard prop type for a Contain CSS component.
+ *
+ * Composes the three things every component's props are made of, and -- the
+ * reason this exists rather than a bare `&` chain -- removes the element
+ * attributes that the style props and the component's own props shadow.
+ * `width`, `height` and `align` are real HTML attributes, so intersecting
+ * `BaseStyleProps` with `HTMLInputAttributes` the old way produced
+ * `(string | null) & (string | number | undefined)` for `width`: a type neither
+ * side meant, which silently accepted and rejected the wrong values.
+ *
+ * @typeParam Attributes - the element's attribute type, e.g. `HTMLButtonAttributes`
+ * @typeParam Own - the component's own props (snippets, variant booleans, ...)
+ * @typeParam Style - the component's style props, e.g. `BaseStyleProps`
+ * @typeParam Owned - attributes the component controls and a caller must not
+ *   set, e.g. `"type"` on Slider's range input. Spreading rest props last means
+ *   a caller's value would otherwise win over the component's own.
+ *
+ * @example
+ * type Props = ContainProps<
+ *   HTMLButtonAttributes,
+ *   { primary?: boolean; children?: Snippet },
+ *   BaseStyleProps
+ * >;
+ */
+export type ContainProps<Attributes, Own = {}, Style = {}, Owned extends keyof Attributes | string = never> = Own & Style & Omit<Attributes, keyof Own | keyof Style | Owned> & CssVarProps;

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
  * Common CSS variable props that can be passed to components.
- * These are converted to CSS custom properties via injectVars().
+ * These are converted to CSS custom properties via elementProps().
  */
 export {};

package/dist/typography/Text.svelte

@@ -1,5 +1,5 @@
-<script lang="ts">import { injectVars } from "../util";
-let { children, primary = false, secondary = false, info = false, success = false, warning = false, danger = false, muted = false, bold = false, italic = false, color, amount, style: inlineStyle, ...restProps } = $props();
+<script lang="ts">import { elementProps } from "../util";
+let { children, primary = false, secondary = false, info = false, success = false, warning = false, danger = false, muted = false, bold = false, italic = false, color, amount, class: className, ...restProps } = $props();
 // Choose one tone deterministically; explicit color takes precedence.
 const tone = $derived(danger
     ? "danger"
@@ -30,17 +30,10 @@ const foreground = $derived.by(() => {
         return mixed;
     return `var(--${tone}-text-fg, ${mixed})`;
 });
-const elementProps = $derived(Object.fromEntries(Object.entries(restProps).filter(([key]) => !key.startsWith("--"))));
-const style = $derived(injectVars(restProps, "text", []) + (inlineStyle ?? ""));
+const el = $derived(elementProps(restProps, "text"));
 </script>
 
-<span
-  {...elementProps}
-  {style}
-  style:color={foreground}
-  class:bold
-  class:italic
->
+<span class={className} class:bold class:italic style:color={foreground} {...el}>
   {@render children?.()}
 </span>
 

package/dist/typography/TextLayout.svelte

@@ -1,12 +1,9 @@
-<script lang="ts">import { injectVars } from "../util";
-let { id = "", marginBlock = null, marginInline = null, children } = $props();
-const style = $derived(injectVars({ marginBlock, marginInline }, "text-layout", [
-    "marginBlock",
-    "marginInline",
-]));
+<script lang="ts">import { elementProps } from "../util";
+let { id = "", children, class: className, ...restProps } = $props();
+const el = $derived(elementProps(restProps, "text-layout", ["marginBlock", "marginInline"]));
 </script>
 
-<div {id} {style}>
+<div {id} class={className} {...el}>
   {@render children?.()}
 </div>
 

package/dist/typography/TextLayout.svelte.d.ts

@@ -1,8 +1,9 @@
-import type { MarginStyleProps } from "../types";
-interface Props extends MarginStyleProps {
+import type { HTMLAttributes } from "svelte/elements";
+import type { ContainProps, MarginStyleProps } from "../types";
+type Props = ContainProps<HTMLAttributes<HTMLDivElement>, {
     id?: string;
     children?: import("svelte").Snippet;
-}
+}, MarginStyleProps>;
 declare const TextLayout: import("svelte").Component<Props, {}, "">;
 type TextLayout = ReturnType<typeof TextLayout>;
 export default TextLayout;

package/dist/util.d.ts

@@ -1,4 +1,61 @@
-export declare function injectVars(props: {
-    [key: string]: any;
-}, prefix: string, varList: string[]): string;
+/**
+ * Split a component's rest props into a `style` string and the attributes that
+ * belong on an element, keeping the two separate.
+ *
+ * Use this for a component that renders a wrapper around a control (Toggle,
+ * RadioButton, Checkbox, FormItem): the CSS variables and the caller's `style`
+ * belong on the wrapper, because that is what the component's own CSS targets
+ * and what a caller expects to position, while `aria-*`, `name`, `required`
+ * and `data-*` belong on the control itself. {@link elementProps} is the
+ * single-element case and is what most components want.
+ *
+ * @returns `style` for the wrapper, `attrs` (never containing `style`) for the
+ *   control.
+ */
+export declare function splitProps(props: Record<string, any>, prefix: string, varList?: readonly string[], extraVars?: string): {
+    style: string;
+    attrs: Record<string, unknown>;
+};
+/**
+ * Split a component's rest props into the attributes that belong on its root
+ * element, with the component's CSS variables and the caller's own `style`
+ * merged into a single `style` attribute.
+ *
+ * This is the one place the library's attribute pass-through contract lives.
+ * It exists because spreading raw rest props gets three things wrong at once:
+ *
+ * 1. **Style props leaked as attributes.** `bg`, `fg`, `padding` and friends are
+ *    read for their CSS variables but were then spread too, rendering invalid
+ *    `<button bg="red">`. Names in `varList` are consumed here, never emitted.
+ * 2. **The caller's `style` clobbered the variables.** `<Tag bg="red" style="margin:0">`
+ *    dropped `--tag-bg` entirely, because the spread's `style` overwrote the
+ *    component's. Both are concatenated instead, caller last so their
+ *    declarations win without erasing the variables.
+ * 3. **Custom properties leaked as attributes.** A spread `{"--tag-bg": "red"}`
+ *    rendered a literal `--tag-bg="red"` attribute. They become declarations.
+ *
+ * `class` is deliberately NOT handled here. Merging it in the template as
+ * `class={["tag", className]}` keeps the component's own class literal in the
+ * markup, which is what lets the compiler's CSS pruning see that `.tag` is used.
+ *
+ * @param props - the component's rest props. Pass style props that were
+ *   destructured out back in explicitly (`{ bg, fg, ...restProps }`) or their
+ *   variables will not be emitted.
+ * @param prefix - CSS variable prefix, e.g. `"tag"` for `--tag-bg`
+ * @param varList - prop names to convert into `--prefix-name` declarations
+ * @param extraVars - variables the component computes itself, e.g.
+ *   `--slider-percent`. Placed after the prop variables and before the
+ *   caller's `style`, so a caller can still override it.
+ *
+ * @example
+ * const el = $derived(elementProps(restProps, "tag", ["bg", "fg", "padding"]));
+ * // <span class={["tag", className]} class:primary {...el}>
+ */
+export declare function elementProps(props: Record<string, any>, prefix: string, varList?: readonly string[], extraVars?: string): Record<string, unknown>;
+/**
+ * Build only the CSS variable string, for a component that has no element to
+ * spread attributes onto (Dialog, which portals its content and copies
+ * variables across).
+ */
+export declare function injectVars(props: Record<string, any>, prefix: string, varList: readonly string[]): string;
 export declare function copyCSSVariables(origin: HTMLElement, target: HTMLElement, variableList?: string[]): void;

package/dist/util.js

@@ -1,19 +1,109 @@
 import { cssProperties } from "./cssprops";
-export function injectVars(props, prefix, varList) {
+/**
+ * Build the `--prefix-name` CSS variable declarations for a component.
+ *
+ * Kept separate from {@link elementProps} only so a component that composes its
+ * style string by hand (Dialog, which also copies variables across a portal)
+ * can reuse the naming rules. Prefer `elementProps` everywhere else.
+ */
+function buildVars(props, prefix, varList) {
     let cssVars = "";
-    varList.forEach((v) => {
-        if (props[v]) {
-            const cssVarName = toKebabCase(v);
-            cssVars += `--${prefix}-${cssVarName}: ${props[v]};`;
-        }
-    });
-    for (let prop in props) {
-        if (prop[0] == "-" && prop[1] == "-") {
-            cssVars += `${prop}: ${props[prop]};`;
-        }
+    for (const name of varList) {
+        const value = props[name];
+        // `0` is a meaningful length, so it is NOT skipped -- the old `if (value)`
+        // test dropped it. `false` still is: Form and Fieldset type `border` as
+        // `string | boolean`, where `false` means "no border", not the declaration
+        // `--form-border: false`.
+        if (value == null || value === "" || value === false)
+            continue;
+        cssVars += `--${prefix}-${toKebabCase(name)}: ${value};`;
+    }
+    for (const key in props) {
+        // Custom properties arriving via an object spread -- see CssVarProps.
+        if (key.startsWith("--"))
+            cssVars += `${key}: ${props[key]};`;
     }
     return cssVars;
 }
+/**
+ * Split a component's rest props into a `style` string and the attributes that
+ * belong on an element, keeping the two separate.
+ *
+ * Use this for a component that renders a wrapper around a control (Toggle,
+ * RadioButton, Checkbox, FormItem): the CSS variables and the caller's `style`
+ * belong on the wrapper, because that is what the component's own CSS targets
+ * and what a caller expects to position, while `aria-*`, `name`, `required`
+ * and `data-*` belong on the control itself. {@link elementProps} is the
+ * single-element case and is what most components want.
+ *
+ * @returns `style` for the wrapper, `attrs` (never containing `style`) for the
+ *   control.
+ */
+export function splitProps(props, prefix, varList = [], extraVars = "") {
+    const attrs = {};
+    for (const key in props) {
+        if (key.startsWith("--"))
+            continue; // becomes a declaration, not an attribute
+        if (key === "style")
+            continue; // returned separately
+        if (varList.includes(key))
+            continue; // a style prop, not an attribute
+        attrs[key] = props[key];
+    }
+    return {
+        style: buildVars(props, prefix, varList) + extraVars + (props.style ?? ""),
+        attrs,
+    };
+}
+/**
+ * Split a component's rest props into the attributes that belong on its root
+ * element, with the component's CSS variables and the caller's own `style`
+ * merged into a single `style` attribute.
+ *
+ * This is the one place the library's attribute pass-through contract lives.
+ * It exists because spreading raw rest props gets three things wrong at once:
+ *
+ * 1. **Style props leaked as attributes.** `bg`, `fg`, `padding` and friends are
+ *    read for their CSS variables but were then spread too, rendering invalid
+ *    `<button bg="red">`. Names in `varList` are consumed here, never emitted.
+ * 2. **The caller's `style` clobbered the variables.** `<Tag bg="red" style="margin:0">`
+ *    dropped `--tag-bg` entirely, because the spread's `style` overwrote the
+ *    component's. Both are concatenated instead, caller last so their
+ *    declarations win without erasing the variables.
+ * 3. **Custom properties leaked as attributes.** A spread `{"--tag-bg": "red"}`
+ *    rendered a literal `--tag-bg="red"` attribute. They become declarations.
+ *
+ * `class` is deliberately NOT handled here. Merging it in the template as
+ * `class={["tag", className]}` keeps the component's own class literal in the
+ * markup, which is what lets the compiler's CSS pruning see that `.tag` is used.
+ *
+ * @param props - the component's rest props. Pass style props that were
+ *   destructured out back in explicitly (`{ bg, fg, ...restProps }`) or their
+ *   variables will not be emitted.
+ * @param prefix - CSS variable prefix, e.g. `"tag"` for `--tag-bg`
+ * @param varList - prop names to convert into `--prefix-name` declarations
+ * @param extraVars - variables the component computes itself, e.g.
+ *   `--slider-percent`. Placed after the prop variables and before the
+ *   caller's `style`, so a caller can still override it.
+ *
+ * @example
+ * const el = $derived(elementProps(restProps, "tag", ["bg", "fg", "padding"]));
+ * // <span class={["tag", className]} class:primary {...el}>
+ */
+export function elementProps(props, prefix, varList = [], extraVars = "") {
+    const { style, attrs } = splitProps(props, prefix, varList, extraVars);
+    if (style)
+        attrs.style = style;
+    return attrs;
+}
+/**
+ * Build only the CSS variable string, for a component that has no element to
+ * spread attributes onto (Dialog, which portals its content and copies
+ * variables across).
+ */
+export function injectVars(props, prefix, varList) {
+    return buildVars(props, prefix, varList);
+}
 function toKebabCase(str) {
     return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "contain-css-svelte",
-  "version": "1.1.20",
+  "version": "1.2.0",
   "license": "MIT",
   "scripts": {
     "capture:review": "node scripts/capture-review.mjs",