contain-css-svelte 1.1.19 → 1.2.0

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.19",
+  "version": "1.2.0",
   "license": "MIT",
   "scripts": {
     "capture:review": "node scripts/capture-review.mjs",