lutra 0.1.68 → 0.1.70

package/dist/components/AspectRatio.svelte

@@ -1,26 +1,36 @@
 <script lang="ts">
     import type { Snippet } from "svelte";
+
+    /**
+     * @description
+     * A wrapper that enforces an aspect ratio on its children. Accepts numeric, ratio string, or colon-separated formats.
+     * @cssprop --aspect-ratio - The aspect ratio of the container. (Default: 16 / 9)
+     * @example
+     * <AspectRatio ratio="4:3">
+     *     <img src="photo.jpg" alt="Photo" style="width: 100%; height: 100%; object-fit: cover;" />
+     * </AspectRatio>
+     */
     let {
-        ratio = 16 / 9,
+        ratio = "16 / 9",
         children
     }: {
-        ratio?: number;
+        /** Aspect ratio as a number (e.g. 1.778), a ratio string (e.g. "16 / 9"), or colon-separated (e.g. "16:9"). */
+        ratio?: number | string;
         children: Snippet;
     } = $props();
+
+    const cssRatio = $derived(
+        typeof ratio === "string" ? ratio.replace(":", " / ") : ratio
+    );
 </script>
 
-<div class="AspectRatio" style="--aspect-ratio: {ratio}">
+<div class="AspectRatio" style="--aspect-ratio: {cssRatio}">
     {@render children()}
 </div>
 
 <style>
-    @property --aspect-ratio {
-        syntax: "<number-percentage> / <number-percentage>";
-        inherits: false;
-        initial-value: 16 / 9;
-    }
     .AspectRatio {
-        aspect-ratio: var(--aspect-ratio);
+        aspect-ratio: var(--aspect-ratio, 16 / 9);
     }
 </style>
 

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

@@ -1,6 +1,7 @@
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
-    ratio?: number;
+    /** Aspect ratio as a number (e.g. 1.778), a ratio string (e.g. "16 / 9"), or colon-separated (e.g. "16:9"). */
+    ratio?: number | string;
     children: Snippet;
 };
 declare const AspectRatio: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/Avatar.svelte

@@ -9,6 +9,9 @@
      * You can pick from three crop styles: circle, square, or rounded. The color of the placeholder is based on the name, making each visually distinct from each other.
      * @cssprop --border-radius - The border radius of the avatar when cropped as rounded.
      * @cssprop --mask-image - Custom mask image to use for the avatar.
+     * @cssprop --size - The size of the avatar. (Default: 3rem)
+     * @cssprop --user-color - The background color of the avatar. (Default: #666666)
+     * @cssprop --text-color - The text color of the avatar. (Default: rgba(0,0,0,0.85))
      * @example
      * <p>With picture:</p>
      * <Avatar name="Auth70" shape="rounded" src="https://avatars.githubusercontent.com/u/122825113?s=200&v=4" --size="4rem" />
@@ -84,11 +87,6 @@
     .Avatar.circle { border-radius: 50%; }
     .Avatar.square { border-radius: 0; }
     .Avatar.rounded { border-radius: var(--border-radius); }
-    .Avatar img {
-        block-size: 100%;
-        inline-size: 100%;
-        object-fit: cover;
-    }
     .Avatar .Placeholder {
         display: flex;
         align-items: center;
@@ -97,9 +95,8 @@
         inline-size: 100%;
         background-color: var(--user-color);
         color: var(--text-color);
-        user-select: none;
-        font-size: 1rem;
-        font-weight: 600;
+        font-size: calc(var(--size, 3rem) * 0.4);
+        font-weight: var(--font-weight-medium);
         user-select: none;
     }
 </style>

package/dist/components/Close.svelte

@@ -1,9 +1,22 @@
 <script lang="ts">
+    /**
+     * @description
+     * A close button rendered as an X icon. Can be absolutely positioned in a corner of its containing element.
+     * @cssprop --close-padding - Padding around the icon. (Default: var(--space-xs))
+     * @cssprop --close-icon-size - Size of the close icon. (Default: max(1.5rem, 1rem))
+     * @example
+     * <div style="position: relative; padding: 2rem; border: 1px solid gray;">
+     *     <Close position="top right" onclick={() => alert('closed')} />
+     *     <p>Content with a close button</p>
+     * </div>
+     */
     let {
         onclick,
         position
     }: {
+        /** Callback when the close button is clicked. */
         onclick?: (e: MouseEvent) => void;
+        /** Absolute position within the parent container. */
         position?: "top left" | "top right" | "bottom left" | "bottom right";
     } = $props();
 </script>
@@ -18,10 +31,9 @@
 <style>
     .Close {
         cursor: pointer;
-        padding: var(--close-padding, 0.5rem);
+        padding: var(--close-padding, var(--space-xs));
         border-radius: 50%;
-        color: var(--text-color, light-dark(black, white));
-        cursor: pointer;
+        color: var(--text-color-p);
         pointer-events: auto;
         border: none;
     }
@@ -40,37 +52,22 @@
     svg {
         display: block;
         margin: 0;
-        width: max(1.5rem, 16px);
-        height: max(1.5rem, 16px);
+        width: var(--close-icon-size, max(1.5rem, 1rem));
+        height: var(--close-icon-size, max(1.5rem, 1rem));
     }
 
     .Close:hover {
-        color: var(--text-color-subtle, light-dark(rgba(0, 0, 0, 0.5), rgba(255, 255, 255, 0.5)));
-    }
-
-    .Close.top {
-        position: absolute;
-        top: 0;
-        right: 0;
-        z-index: 100;
+        color: var(--text-color-p-subtle);
     }
 
+    .Close.top,
     .Close.bottom {
         position: absolute;
-        bottom: 0;
-        right: 0;
-    }
-
-    .Close.left {
-        position: absolute;
-        top: 0;
-        left: 0;
-        right: auto;
+        z-index: 100;
     }
 
-    .Close.right {
-        position: absolute;
-        top: 0;
-        right: 0;
-    }
+    .Close.top.right  { inset: 0 0 auto auto; }
+    .Close.top.left   { inset: 0 auto auto 0; }
+    .Close.bottom.right { inset: auto 0 0 auto; }
+    .Close.bottom.left  { inset: auto auto 0 0; }
 </style>

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

@@ -1,5 +1,7 @@
 type $$ComponentProps = {
+    /** Callback when the close button is clicked. */
     onclick?: (e: MouseEvent) => void;
+    /** Absolute position within the parent container. */
     position?: "top left" | "top right" | "bottom left" | "bottom right";
 };
 declare const Close: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/ContextTip.svelte

@@ -18,7 +18,7 @@
 </script>
 
 <Tooltip {tip}>
-    <a href="#contexttip" onclick={(e) => { e.preventDefault(); e.stopPropagation(); }}>
+    <a class="ContextTip" href="#contexttip" onclick={(e) => { e.preventDefault(); e.stopPropagation(); }}>
         <Icon icon={Help} --icon-width="16px" --icon-height="16px" --cursor="help" --vertical-align="baseline" />
     </a>
 </Tooltip>
@@ -35,7 +35,8 @@
         justify-content: center;
     }
     a:focus-visible {
-        color: var(--focus-ring-color);
+        outline: var(--focus-ring);
         outline-offset: 0px;
+        color: var(--focus-ring-color);
     }
 </style>

package/dist/components/DataList.svelte

@@ -0,0 +1,111 @@
+<script lang="ts">
+	import type { DataListItem } from "./DataListTypes.js";
+
+    /**
+     * @description
+     * Renders an array of label/value pairs as a semantic description list (`<dl>`).
+     * Supports horizontal (side-by-side), vertical (stacked), or auto (container-query
+     * responsive) layouts. Values can be plain strings, snippets, render functions,
+     * or components.
+     *
+     * @cssprop --data-list-gap -- Gap between items in the list.
+     *
+     * @example
+     * <DataList items={[
+     *     { label: 'Name', value: 'Alice' },
+     *     { label: 'Email', value: 'alice@example.com' },
+     * ]} />
+     */
+    let {
+        items,
+        direction = 'auto',
+    }: {
+        /** The data items to display. */
+        items: DataListItem[];
+        /** Layout direction. 'auto' switches from horizontal to vertical based on container width. */
+        direction?: 'horizontal' | 'vertical' | 'auto';
+    } = $props();
+</script>
+
+<div class="DataList">
+    <dl class={direction}>
+        {#each items as item}
+            <div>
+                <dt>{item.label}</dt>
+                <dd>
+                    {#if item.snippet}
+                        {@render item.snippet()}
+                    {:else if item.render}
+                        {@render item.render()}
+                    {:else if item.component}
+                        <item.component />
+                    {:else if item.value}
+                        {item.value}
+                    {/if}
+                </dd>
+            </div>
+        {/each}
+    </dl>
+</div>
+
+<style>
+    .DataList {
+        container-type: inline-size;
+    }
+
+    dl {
+        margin: 0;
+        padding: 0;
+    }
+
+    dt {
+        color: var(--text-color-p-subtle);
+    }
+
+    dd {
+        margin: 0;
+        color: var(--text-color-p);
+    }
+
+    /**
+     * Horizontal layout: two-column grid with subgrid for aligned labels
+     */
+    dl.horizontal,
+    dl.auto {
+        display: grid;
+        grid-template-columns: auto 1fr;
+        gap: var(--data-list-gap);
+    }
+
+    dl.horizontal > div,
+    dl.auto > div {
+        display: grid;
+        grid-column: 1 / -1;
+        grid-template-columns: subgrid;
+        align-items: baseline;
+    }
+
+    /**
+     * Vertical layout: stacked label over value
+     */
+    dl.vertical {
+        display: flex;
+        flex-direction: column;
+        gap: var(--data-list-gap);
+    }
+
+    /**
+     * Auto: switch to vertical when the container is narrow
+     */
+    @container (max-width: 300px) {
+        dl.auto {
+            display: flex;
+            flex-direction: column;
+        }
+
+        dl.auto > div {
+            display: flex;
+            flex-direction: column;
+        }
+    }
+</style>

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

@@ -0,0 +1,10 @@
+import type { DataListItem } from "./DataListTypes.js";
+type $$ComponentProps = {
+    /** The data items to display. */
+    items: DataListItem[];
+    /** Layout direction. 'auto' switches from horizontal to vertical based on container width. */
+    direction?: 'horizontal' | 'vertical' | 'auto';
+};
+declare const DataList: import("svelte").Component<$$ComponentProps, {}, "">;
+type DataList = ReturnType<typeof DataList>;
+export default DataList;

package/dist/components/DataListTypes.d.ts

@@ -0,0 +1,14 @@
+import type { Component, Snippet } from "svelte";
+import type { RenderFn } from "../types.js";
+export type DataListItem = {
+    /** Text label for the item (e.g. "Status", "Email") */
+    label: string;
+    /** Text value to display */
+    value?: string;
+    /** Snippet to render as the value */
+    snippet?: Snippet;
+    /** Render function for the value (works in object literals) */
+    render?: RenderFn;
+    /** Component to render as the value */
+    component?: Component;
+};

package/dist/components/DataListTypes.js

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

package/dist/components/Dialog.svelte

@@ -2,8 +2,14 @@
     import type { Snippet } from "svelte";
 
     /**
+     * @description
      * A simple dialog component using the native `<dialog>` element.
      * For more features (buttons, scrim control, etc.), use `<Modal>` instead.
+     * Uses modal tokens for styling (background, border, padding, shadow, etc.).
+     * @example
+     * <Dialog bind:open={showDialog} title="Confirm">
+     *     <p>Are you sure?</p>
+     * </Dialog>
      */
     let {
         open = $bindable(false),
@@ -81,6 +87,38 @@
     .Dialog[open] {
         display: grid;
         grid-template-rows: auto 1fr;
+        opacity: 1;
+        translate: 0 0;
+        transition:
+            opacity var(--transition-duration-fast) ease-out,
+            translate var(--transition-duration-fast) ease-out,
+            display var(--transition-duration-fast) allow-discrete,
+            overlay var(--transition-duration-fast) allow-discrete;
+    }
+
+    .Dialog[open]::backdrop {
+        opacity: 1;
+        transition:
+            opacity var(--transition-duration-fast) ease-out,
+            display var(--transition-duration-fast) allow-discrete,
+            overlay var(--transition-duration-fast) allow-discrete;
+    }
+
+    @starting-style {
+        .Dialog[open] {
+            opacity: 0;
+            translate: 0 var(--space-xs);
+        }
+        .Dialog[open]::backdrop {
+            opacity: 0;
+        }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        .Dialog,
+        .Dialog::backdrop {
+            transition: none;
+        }
     }
 
     .DialogHeader {

package/dist/components/Icon.svelte

@@ -4,8 +4,8 @@
     /**
      * @description
      * A component that displays an icon. It can be an image url or a component. The icon will be centered in the container.
-     * @cssprop --icon-width - The width of the icon. (Default: var(--font-size, 1em))
-     * @cssprop --icon-height - The height of the icon. (Default: var(--font-size, 1em))
+     * @cssprop --icon-width - The width of the icon. (Default: font-size or 1rem)
+     * @cssprop --icon-height - The height of the icon. (Default: font-size or 1rem)
      * @cssprop --icon-color - The color of the icon. (Default: var(--text-color, currentColor))
      * @example
      * <script>

package/dist/components/IconButton.svelte

@@ -9,7 +9,7 @@
      * A component that displays an icon with a possible label. It can also have a click event.
      * The button has a padding of 0.75em by default to make it easier to tap on mobile devices. The padding can be changed using the `--padding` CSS variable.
      * Icon and text color will be inherited from the parent element.
-     * @cssprop --padding - The padding of the icon button. (Default: 0.75em)
+     * @cssprop --padding - The padding of the icon button. (Default: var(--space-sm))
      * @example
      * <script>
      * import Copy from 'lutra/Icons/Copy.svelte';
@@ -71,10 +71,11 @@
         color: inherit;
         opacity: 1;
         background-color: var(--field-background-color, transparent);
-        transition: background-color 0.04s;
+        transition: background-color var(--transition-duration-fast);
         border-radius: var(--field-border-radius);
     }
-    .IconButton:hover {
+    .IconButton:hover,
+    .IconButton:focus-visible {
         background-color: var(--menu-background-color-hover);
     }
     .IconButton:active {
@@ -84,37 +85,24 @@
         border: none;
         background: none;
         cursor: pointer;
-        color: var(--text-color-p, light-dark(black, white));
     }
     .IconMask {
         height: 100%;
-        padding-inline: calc(var(--padding, 0.75em) * 0.8);
-        padding-block: calc(var(--padding, 0.75em) * 0.8);
+        padding-inline: calc(var(--padding, var(--space-sm)) * 0.8);
+        padding-block: calc(var(--padding, var(--space-sm)) * 0.8);
         display: inline-grid;
-        gap: 0.5rem;
+        gap: var(--space-xs);
         grid-template: "icon";
         align-items: center;
     }
     .IconMask.mask {
-        -webkit-mask-image: linear-gradient(to bottom, rgba(0, 0, 0, 0), rgba(0, 0, 0, 1) 35%, rgba(0, 0, 0, 1) 65%, rgba(0, 0, 0, 0));
-        mask-image: linear-gradient(to bottom, rgba(0, 0, 0, 0), rgba(0, 0, 0, 1) 35%, rgba(0, 0, 0, 1) 65%, rgba(0, 0, 0, 0));
+        -webkit-mask-image: linear-gradient(to bottom, transparent, black 35%, black 65%, transparent);
+        mask-image: linear-gradient(to bottom, transparent, black 35%, black 65%, transparent);
     }
     .IconContent {
         grid-area: icon;
         display: inline-flex;
-        gap: 0.5rem;
+        gap: var(--space-xs);
         align-items: center;
     }
-    @media(max-width: 960px) {
-        .IconMask {
-            padding-inline: calc(var(--padding, 0.75em) * 0.75);
-            padding-block: calc(var(--padding, 0.75em) * 0.75);
-        }
-    }
-    @media(max-width: 320px) {
-        .IconMask {
-            padding-inline: calc(var(--padding, 0.75em) * 0.6);
-            padding-block: calc(var(--padding, 0.75em) * 0.6);
-        }
-    }
 </style>

package/dist/components/Image.svelte

@@ -9,7 +9,7 @@
      * <Image aspectRatio="16:9" fit="cover" src="https://images.unsplash.com/photo-1712337646541-d0c6f85447f8" alt="An example image" />
      */
     
-	import { browser } from "$app/environment";
+	import { BROWSER } from 'esm-env';
     import { decode } from "blurhash";
 	import { fade } from "svelte/transition";
 
@@ -94,7 +94,7 @@
     }
 
     let decoded = $state(false);
-    let loaded = $state(browser ? false : true);
+    let loaded = $state(BROWSER ? false : true);
 
     const onload = () => {
         loaded = true;

package/dist/components/Indicator.svelte

@@ -43,7 +43,7 @@
     let _label = $derived(isSet ? StatusColors[color as StatusColor] : label ? label : 'status');
 </script>
 
-<span role="status" aria-label="{_label}" class="Indicator {color} {motion}" style="--bgColor: {isSet ? 'var(--status-'+color+')' : color};"></span>
+<span role="status" aria-label="{_label}" class="Indicator {color} {motion}" style="--bgColor: {isSet ? 'var(--status-'+color+'-color)' : color};"></span>
 
 <style>
     .Indicator {
@@ -242,6 +242,7 @@
         --mask: radial-gradient(circle, rgba(0, 0, 0, 0) 20%, rgba(0, 0, 0, 0) 45%, black 50%, black 100%);
         -webkit-mask-image: var(--mask);
         mask-image: var(--mask);
+        mask-size: 100% 100%;
         filter: drop-shadow(0 0 calc(var(--isize) * 0.05) var(--bgColor));
     }
     .Indicator.spin::after,

package/dist/components/Inset.svelte

@@ -1,6 +1,19 @@
 <script lang="ts">
     import type { Snippet } from "svelte";
 
+    /**
+     * @description
+     * Negates the padding of a parent container by applying negative margins, allowing child content (e.g. images) to span edge-to-edge.
+     * Reads `--inset-block` and `--inset-inline` from the parent context (typically set by MenuItem or similar).
+     * @cssprop --inset-block - The block inset to negate. (Default: 0)
+     * @cssprop --inset-inline - The inline inset to negate. (Default: 0)
+     * @example
+     * <div style="padding: 1rem; --inset-block: 1rem; --inset-inline: 1rem;">
+     *     <Inset>
+     *         <img src="banner.jpg" alt="Full-bleed banner" />
+     *     </Inset>
+     * </div>
+     */
     let {
         children,
     }: {

package/dist/components/Layout.svelte

@@ -1,22 +1,26 @@
 <script lang="ts">
-	import type { Snippet } from "svelte";
+	import { getContext, type Snippet } from "svelte";
 	import "../css/lutra.css";
 	import Theme from "./Theme.svelte";
 	import ToastContainer from "./ToastContainer.svelte";
+    import { getContextItem, LutraContext, type LutraContextTypeMap, type LutraTheme } from "../types.js";
+
+	const lutra = getContext<() => LutraContextTypeMap>('lutra');
 
 	/**
 	 * Default layout component that imports styles and provides theming.
 	 * Includes ToastContainer for toast notifications.
 	 */
 	let {
-		theme,
+		theme = lutra()?.[LutraContext.Theme]?.() ?? "system",
 		children,
 	}: { 
 		/** The theme to use. Leave empty for auto-detection. */
-		theme?: 'light' | 'dark' | undefined;
+		theme?: LutraTheme;
 		/** The content to display. */
 		children: Snippet;
 	} = $props();
+
 </script>
 
 <Theme theme={theme}>

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

@@ -1,8 +1,9 @@
-import type { Snippet } from "svelte";
+import { type Snippet } from "svelte";
 import "../css/lutra.css";
+import { type LutraTheme } from "../types.js";
 type $$ComponentProps = {
     /** The theme to use. Leave empty for auto-detection. */
-    theme?: 'light' | 'dark' | undefined;
+    theme?: LutraTheme;
     /** The content to display. */
     children: Snippet;
 };

package/dist/components/MenuDropdown.svelte

@@ -7,8 +7,18 @@
 	import { arrowNavigation, matchOnType } from "../util/keyboard.svelte.js";
 
 	/**
-	 * A dropdown menu using the base Popover component.
-	 * Handles menu-specific keyboard navigation and item rendering.
+	 * @description
+	 * A dropdown menu built on the Popover component. Handles keyboard navigation (arrow keys, type-ahead)
+	 * and renders MenuItem entries. Uses menu tokens for styling via the Popover's CSS variable overrides.
+	 * @example
+	 * <MenuDropdown
+	 *     trigger="Options"
+	 *     items={[
+	 *         { type: 'item', text: 'Edit', onclick: () => {} },
+	 *         { type: 'divider' },
+	 *         { type: 'item', text: 'Delete', color: 'alert', onclick: () => {} },
+	 *     ]}
+	 * />
 	 */
 	let {
 		open = $bindable(false),