feat: Add @layerstack/svelte-attachments package

.changeset/real-keys-battle.md

@@ -0,0 +1,5 @@
+---
+'@layerstack/svelte-attachments': minor
+---
+
+feat: Add `@layerstack/svelte-attachments` package

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024 Sean Lynch
+Copyright (c) 2025 Sean Lynch
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package.json

@@ -17,10 +17,10 @@
     "up-deps": "pnpm update -r -i --latest"
   },
   "devDependencies": {
-    "@changesets/cli": "2.29.4",
+    "@changesets/cli": "2.29.6",
     "@svitejs/changesets-changelog-github-compact": "^1.2.0",
     "rimraf": "6.0.1",
-    "wrangler": "^4.14.4"
+    "wrangler": "^4.33.1"
   },
   "packageManager": "[email protected]"
 }

packages/svelte-actions/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024 Sean Lynch
+Copyright (c) 2025 Sean Lynch
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

packages/svelte-actions/package.json

@@ -18,23 +18,23 @@
     "format": "prettier --write ."
   },
   "devDependencies": {
-    "@sveltejs/package": "^2.3.11",
-    "@sveltejs/vite-plugin-svelte": "^5.0.3",
+    "@sveltejs/package": "^2.5.0",
+    "@sveltejs/vite-plugin-svelte": "^6.1.3",
     "@types/d3-scale": "^4.0.9",
-    "prettier": "^3.5.3",
-    "prettier-plugin-svelte": "^3.3.3",
+    "prettier": "^3.6.2",
+    "prettier-plugin-svelte": "^3.4.0",
     "rimraf": "6.0.1",
-    "svelte": "^5.28.2",
-    "svelte-check": "^4.1.6",
-    "svelte2tsx": "^0.7.36",
+    "svelte": "^5.38.6",
+    "svelte-check": "^4.3.1",
+    "svelte2tsx": "^0.7.42",
     "tslib": "^2.8.1",
-    "typescript": "^5.8.3",
-    "vite": "^6.3.5",
-    "vitest": "^3.1.3"
+    "typescript": "^5.9.2",
+    "vite": "^7.1.3",
+    "vitest": "^3.2.4"
   },
   "type": "module",
   "dependencies": {
-    "@floating-ui/dom": "^1.7.0",
+    "@floating-ui/dom": "^1.7.4",
     "@layerstack/utils": "workspace:*",
     "d3-scale": "^4.0.2"
   },

packages/svelte-attachments/.prettierignore

@@ -0,0 +1,15 @@
+.DS_Store
+node_modules
+/build
+/dist
+/.svelte-kit
+/package
+.env
+.env.*
+!.env.example
+coverage/
+
+# Ignore files for PNPM, NPM and YARN
+pnpm-lock.yaml
+package-lock.json
+yarn.lock

packages/svelte-attachments/CHANGELOG.md

@@ -0,0 +1 @@
+# @layerstack/svelte-attachments

packages/svelte-attachments/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Sean Lynch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/svelte-attachments/README.md

@@ -0,0 +1,9 @@
+# LayerStack svelte-attachments
+
+![](https://img.shields.io/github/license/techniq/layerstack?style=flat)
+[![](https://img.shields.io/github/actions/workflow/status/techniq/layerstack/ci.yml?style=flat)](https://github.com/techniq/layerstack/actions/workflows/ci.yml)
+
+![](https://img.shields.io/github/license/layerstack?style=flat)
+[![](https://dcbadge.vercel.app/api/server/697JhMPD3t?style=flat)](https://discord.gg/697JhMPD3t)
+
+See also the companion libraries [LayerChart](https://layerchart.com) for a large collection of composable chart components to build a wide range of visualizations, and [Svelte UX](https://svelte-ux.techniq.dev/) for a collection of components to build highly interactive applications.

packages/svelte-attachments/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@layerstack/svelte-attachments",
+  "description": "TODO",
+  "author": "Sean Lynch <[email protected]>",
+  "license": "MIT",
+  "repository": "techniq/layerstack",
+  "version": "0.0.0",
+  "scripts": {
+    "dev": "rimraf dist && tsc -p tsconfig.build.json --watch",
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "preview": "vite preview",
+    "package": "svelte-package",
+    "prepublishOnly": "svelte-package",
+    "check": "svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-check --tsconfig ./tsconfig.json --watch",
+    "test:unit": "TZ=UTC+4 vitest",
+    "lint": "prettier --check .",
+    "format": "prettier --write ."
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.5.0",
+    "@sveltejs/vite-plugin-svelte": "^6.1.3",
+    "@types/d3-array": "^3.2.1",
+    "@types/d3-scale": "^4.0.9",
+    "@types/lodash-es": "^4.17.12",
+    "@vitest/coverage-v8": "^3.0.7",
+    "prettier": "^3.6.2",
+    "prettier-plugin-svelte": "^3.4.0",
+    "rimraf": "6.0.1",
+    "svelte": "^5.38.6",
+    "svelte-check": "^4.3.1",
+    "svelte2tsx": "^0.7.42",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.3",
+    "vitest": "^3.2.4"
+  },
+  "type": "module",
+  "dependencies": {
+    "@floating-ui/dom": "^1.7.4",
+    "@layerstack/utils": "workspace:*",
+    "d3-array": "^3.2.4",
+    "d3-scale": "^4.0.2",
+    "date-fns": "^4.1.0",
+    "lodash-es": "^4.17.21"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "svelte": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.d.ts"
+  ],
+  "svelte": "./dist/index.js"
+}

packages/svelte-attachments/src/lib/dataBackground.svelte.ts

@@ -0,0 +1,144 @@
+import { untrack } from 'svelte';
+import { Attachment } from 'svelte/attachments';
+import { Tween } from 'svelte/motion';
+import { EasingFunction } from 'svelte/transition';
+import { scaleLinear } from 'd3-scale';
+
+export type DataBackgroundOptions = {
+  value: number | null | undefined;
+  domain?: [number, number];
+
+  /**
+   * Set color explicitly.  Can also use the following:
+   *   - tailwind gradient classes (`from-blue-200 to-blue-400`)
+   *   - Set CSS variables `--color-from` and `--color-to`
+   */
+  color?: string | ((value: number) => string);
+
+  /**
+   * Render as bar or fill (heatmap)
+   */
+  mode?: 'bar' | 'fill';
+
+  /** Inset bar.  Pass as [x,y] to specify per axis */
+  inset?: number | [number, number];
+
+  enabled?: boolean;
+
+  /**
+   * Show baseline
+   */
+  baseline?: boolean;
+
+  tween?: { duration?: number; easing?: EasingFunction; delay?: number };
+};
+
+export function dataBackground(getOptions: () => DataBackgroundOptions): Attachment<HTMLElement> {
+  return (node: HTMLElement) => {
+    // TODO: Should we track `tween`-only options to not require `{#key}`
+    const tweenOptions = untrack(() => {
+      // Set duration to 0 by default to be instantaneous
+      return { duration: 0, ...getOptions().tween };
+    });
+    const baseline = new Tween(0, tweenOptions);
+    const barStart = new Tween(0, tweenOptions);
+    const barEnd = new Tween(0, tweenOptions);
+
+    // Update CSS properties reactively using $effect
+    $effect(() => {
+      node.style.setProperty('--baseline', `${baseline.current}%`);
+      node.style.setProperty('--barStart', `${barStart.current}%`);
+      node.style.setProperty('--barEnd', `${barEnd.current}%`);
+    });
+
+    $effect(() => {
+      const options = getOptions();
+      const { domain, color, mode = 'bar', inset, enabled } = options;
+
+      const value = options.value ?? 0;
+
+      if (enabled === false) {
+        // remove styles
+        node.style.backgroundImage = '';
+        node.style.backgroundRepeat = '';
+        node.style.backgroundSize = '';
+      } else {
+        // Map values from 0% to 100%
+        const scale = scaleLinear()
+          .domain(domain ?? [-100, 100])
+          .range([0, 100]);
+
+        baseline.target = scale(0);
+        barStart.target = scale(Math.min(0, value));
+        barEnd.target = scale(Math.max(0, value));
+
+        node.style.setProperty(
+          '--color-from',
+          (typeof color === 'function' ? color(value) : color) ?? 'var(--tw-gradient-from)'
+        );
+        node.style.setProperty(
+          '--color-to',
+          (typeof color === 'function' ? color(value) : color) ?? 'var(--tw-gradient-to)'
+        );
+
+        const insetX = Array.isArray(inset) ? inset[0] : inset;
+        const insetY = Array.isArray(inset) ? inset[1] : inset;
+
+        node.style.backgroundSize = `
+			calc(100% - (${insetX}px * 2))
+			calc(100% - (${insetY}px * 2))`;
+        node.style.backgroundPosition = `${insetX}px ${insetY}px`;
+
+        // Show black baseline at `0` first, then value bar
+        // TODO: Handle baseline at `100%` (only negative numbers)
+        node.style.backgroundImage =
+          mode === 'bar'
+            ? `${
+                options.baseline
+                  ? `
+            linear-gradient(
+              to right,
+              transparent var(--baseline),
+              currentColor var(--baseline),
+              currentColor calc(var(--baseline) + 1px),
+              transparent 0%,
+              transparent 100%
+            ),
+          `
+                  : ''
+              }
+            linear-gradient(
+              to right,
+              transparent var(--barStart),
+              var(--color-from) var(--barStart),
+              var(--color-to) var(--barEnd),
+              transparent 0%,
+              transparent 100%
+            )
+          `
+            : `linear-gradient(
+          to right,
+          var(--color-from),
+          var(--color-to)
+        )`;
+
+        // Add `no-repeat` to fix small gap on 100% and also support `background-origin` setting (inset)
+        node.style.backgroundRepeat = 'no-repeat';
+      }
+    });
+
+    // Return cleanup function
+    return () => {
+      // Clean up styles
+      node.style.backgroundImage = '';
+      node.style.backgroundRepeat = '';
+      node.style.backgroundSize = '';
+      node.style.backgroundPosition = '';
+      node.style.removeProperty('--baseline');
+      node.style.removeProperty('--barStart');
+      node.style.removeProperty('--barEnd');
+      node.style.removeProperty('--color-from');
+      node.style.removeProperty('--color-to');
+    };
+  };
+}

packages/svelte-attachments/src/lib/focus.ts

@@ -0,0 +1,48 @@
+import { Attachment } from 'svelte/attachments';
+import { delay } from '@layerstack/utils';
+
+export function focusMove(
+  options: { restoreFocus?: boolean; delay?: number; disabled?: boolean } = {
+    restoreFocus: false,
+    delay: 0,
+    disabled: false,
+  }
+): Attachment<HTMLElement | SVGElement> {
+  return (node: HTMLElement | SVGElement) => {
+    let previousActiveElement: Element | null = null;
+
+    if (!options.disabled) {
+      previousActiveElement = document.activeElement;
+
+      // Set `tabIndex` to `-1` which makes any element (ex. div) focusable programmaitcally (and mouse), but not via keyboard navigation - https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex
+      node.tabIndex = -1;
+
+      // Appear to need to wait for tabIndex to update before applying focus
+      delay(options.delay ?? 0).then(() => {
+        node.focus();
+      });
+    }
+
+    return () => {
+      // Restore previous active element
+      if (
+        !options.disabled &&
+        options.restoreFocus &&
+        previousActiveElement instanceof HTMLElement
+      ) {
+        previousActiveElement.focus();
+      }
+    };
+  };
+}
+
+// TODO: Add `focusTrap`
+// https://css-tricks.com/a-css-approach-to-trap-focus-inside-of-an-element/
+// export function focusTrap(): Attachment<HTMLElement> {
+//   return (node: HTMLElement) => {
+//     // TODO: Implementation
+//     return () => {
+//       // cleanup
+//     };
+//   };
+// }

packages/svelte-attachments/src/lib/index.ts

@@ -0,0 +1,13 @@
+export * from './dataBackground.svelte.js';
+export * from './focus.js';
+export * from './input.js';
+// export * from './layout.js';
+// export * from './mouse.js';
+// export * from './multi.js';
+// export * from './observer.js';
+// export * from './popover.js';
+// export * from './portal.js';
+// export * from './scroll.js';
+// export * from './spotlight.js';
+// export * from './sticky.js';
+// export * from './styles.js';