@streamscloud/kit 0.22.0 → 0.23.0

package/dist/ui/fit-box/cmp.fit-box.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">import { containFit } from './contain-fit';
+const { basis = 'box', allowUpscale = false, alignInline = 'center', alignBlock = 'center', children } = $props();
+</script>
+
+<div class="fit-box">
+  <div class="fit-box__scaler" class:fit-box__scaler--natural={basis === 'content'} use:containFit={{ allowUpscale, alignInline, alignBlock }}>
+    {@render children()}
+  </div>
+</div>
+
+<!--
+@component
+Scales its content as one unit to fit the box like `object-fit: contain` — proportions preserved, bounded by both the box's width and
+height, no crop, no scroll. A generic fit primitive for **cards and media content** (a card, an image/video, a fixed-size widget), not a
+page-layout tool.
+
+How it works: the box is `FitBox`'s **parent**, which must have a **definite size** (fixed / `%` / grid-track / aspect-ratio+width — a
+content-driven `height: auto` parent collapses and nothing shows). The content is measured, then transform-scaled by
+`min(boxW / contentW, boxH / contentH)` and positioned; a `ResizeObserver` re-fits on any box or content change.
+
+Pick the mode with `basis`:
+- `basis="box"` (default) — fluid, width-driven content (cards, text, single-aspect media). Fills the box width, scales down to fit the
+  height. Never enlarges.
+- `basis="content"` — intrinsic content (`<img>` / `<video>`, fixed-size widgets). Keeps the content's natural size and fits both axes;
+  set `allowUpscale` to also enlarge it to fill.
+
+`alignInline` / `alignBlock` place the content along an axis when fitting leaves free space there. Requires client-side JS (scales via
+`transform`, so `position: fixed` descendants are relative to the box); content with a hard fixed width wider than the box is clipped
+rather than contained.
+-->
+
+<style>.fit-box {
+  position: relative;
+  inline-size: 100%;
+  block-size: 100%;
+  overflow: hidden;
+}
+.fit-box__scaler {
+  position: absolute;
+  inline-size: 100%;
+  max-inline-size: 100%;
+  visibility: hidden;
+}
+.fit-box__scaler--natural {
+  inline-size: auto;
+}</style>

package/dist/ui/fit-box/cmp.fit-box.svelte.d.ts

@@ -0,0 +1,42 @@
+import type { FitAlign, FitBasis } from './types';
+import type { Snippet } from 'svelte';
+type Props = {
+    /**
+     * What the content's width is based on before it is scaled to fit:
+     * - `'box'` — content is laid out at the **box width** first (use for fluid, width-driven content: a card, a text block, single-aspect
+     *   media). Height follows from that width; the content is then scaled **down** only if too tall. Never enlarges.
+     * - `'content'` — content keeps its **own natural size** (use for intrinsic content: `<img>` / `<video>`, a fixed-size widget). It is
+     *   scaled to fit **both** axes and may be enlarged when `allowUpscale` is set.
+     * @default 'box'
+     */
+    basis?: FitBasis;
+    /** Allow scaling content up past its natural size to fill the box. Takes effect only with `basis="content"` (`'box'` never enlarges). @default false */
+    allowUpscale?: boolean;
+    /** Inline-axis (horizontal) placement of the fitted content, visible only when free width remains after fitting. @default 'center' */
+    alignInline?: FitAlign;
+    /** Block-axis (vertical) placement of the fitted content, visible only when free height remains after fitting. @default 'center' */
+    alignBlock?: FitAlign;
+    children: Snippet;
+};
+/**
+ * Scales its content as one unit to fit the box like `object-fit: contain` — proportions preserved, bounded by both the box's width and
+ * height, no crop, no scroll. A generic fit primitive for **cards and media content** (a card, an image/video, a fixed-size widget), not a
+ * page-layout tool.
+ *
+ * How it works: the box is `FitBox`'s **parent**, which must have a **definite size** (fixed / `%` / grid-track / aspect-ratio+width — a
+ * content-driven `height: auto` parent collapses and nothing shows). The content is measured, then transform-scaled by
+ * `min(boxW / contentW, boxH / contentH)` and positioned; a `ResizeObserver` re-fits on any box or content change.
+ *
+ * Pick the mode with `basis`:
+ * - `basis="box"` (default) — fluid, width-driven content (cards, text, single-aspect media). Fills the box width, scales down to fit the
+ * height. Never enlarges.
+ * - `basis="content"` — intrinsic content (`<img>` / `<video>`, fixed-size widgets). Keeps the content's natural size and fits both axes;
+ * set `allowUpscale` to also enlarge it to fill.
+ *
+ * `alignInline` / `alignBlock` place the content along an axis when fitting leaves free space there. Requires client-side JS (scales via
+ * `transform`, so `position: fixed` descendants are relative to the box); content with a hard fixed width wider than the box is clipped
+ * rather than contained.
+ */
+declare const Cmp: import("svelte").Component<Props, {}, "">;
+type Cmp = ReturnType<typeof Cmp>;
+export default Cmp;

package/dist/ui/fit-box/contain-fit.d.ts

@@ -0,0 +1,8 @@
+import type { FitAlign } from './types';
+import type { Action } from 'svelte/action';
+export type ContainFitParams = {
+    allowUpscale?: boolean;
+    alignInline?: FitAlign;
+    alignBlock?: FitAlign;
+};
+export declare const containFit: Action<HTMLElement, ContainFitParams | undefined>;

package/dist/ui/fit-box/contain-fit.js

@@ -0,0 +1,47 @@
+const offset = (align, free) => (align === 'start' ? 0 : align === 'end' ? free : free / 2);
+export const containFit = (node, params = {}) => {
+    const container = node.parentElement;
+    let allowUpscale = params.allowUpscale ?? false;
+    let alignInline = params.alignInline ?? 'center';
+    let alignBlock = params.alignBlock ?? 'center';
+    const apply = () => {
+        if (!container) {
+            return;
+        }
+        const boxWidth = container.clientWidth;
+        const boxHeight = container.clientHeight;
+        const naturalWidth = node.offsetWidth;
+        const naturalHeight = node.offsetHeight;
+        if (!boxWidth || !boxHeight || !naturalWidth || !naturalHeight) {
+            return;
+        }
+        let scale = Math.min(boxWidth / naturalWidth, boxHeight / naturalHeight);
+        if (!allowUpscale) {
+            scale = Math.min(scale, 1);
+        }
+        const left = offset(alignInline, boxWidth - naturalWidth * scale);
+        const top = offset(alignBlock, boxHeight - naturalHeight * scale);
+        node.style.transformOrigin = '0 0';
+        node.style.transform = `scale(${scale})`;
+        node.style.left = `${left}px`;
+        node.style.top = `${top}px`;
+        node.style.visibility = 'visible';
+    };
+    const observer = new ResizeObserver(apply);
+    if (container) {
+        observer.observe(container);
+    }
+    observer.observe(node);
+    apply();
+    return {
+        update(next = {}) {
+            allowUpscale = next.allowUpscale ?? false;
+            alignInline = next.alignInline ?? 'center';
+            alignBlock = next.alignBlock ?? 'center';
+            apply();
+        },
+        destroy() {
+            observer.disconnect();
+        }
+    };
+};

package/dist/ui/fit-box/index.d.ts

@@ -0,0 +1,2 @@
+export { default as FitBox } from './cmp.fit-box.svelte';
+export type { FitAlign, FitBasis } from './types';

package/dist/ui/fit-box/index.js

@@ -0,0 +1 @@
+export { default as FitBox } from './cmp.fit-box.svelte';

package/dist/ui/fit-box/types.d.ts

@@ -0,0 +1,2 @@
+export type FitAlign = 'start' | 'center' | 'end';
+export type FitBasis = 'box' | 'content';

package/dist/ui/fit-box/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamscloud/kit",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "author": "StreamsCloud",
   "repository": {
     "type": "git",
@@ -195,6 +195,10 @@
       "types": "./dist/ui/file-uploader/index.d.ts",
       "svelte": "./dist/ui/file-uploader/index.js"
     },
+    "./ui/fit-box": {
+      "types": "./dist/ui/fit-box/index.d.ts",
+      "svelte": "./dist/ui/fit-box/index.js"
+    },
     "./ui/form-field": {
       "types": "./dist/ui/form-field/index.d.ts",
       "svelte": "./dist/ui/form-field/index.js"