lutra 0.1.68 → 0.1.69

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/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),

package/dist/components/MenuItem.svelte

@@ -3,6 +3,17 @@
     import MenuItemContent from "./MenuItemContent.svelte";
 	import type { MenuItem as Item } from "./MenuTypes.js";
 
+    /**
+     * @description
+     * A single menu item within a menu list. Supports item, header, text, and divider types.
+     * Items can be links, buttons, or custom rendered content. Keyboard navigation is handled by the parent MenuDropdown.
+     * @cssprop --menu-item-font-size - Font size of the menu item. (Default: var(--font-size-sm))
+     * @cssprop --menu-item-padding-block - Block padding of the menu item. (Default: var(--space-xs))
+     * @cssprop --menu-item-padding-inline - Inline padding of the menu item. (Default: var(--space-md))
+     * @cssprop --menu-item-gap - Gap between icon and text within the item. (Default: var(--space-sm))
+     * @cssprop --menu-item-margin - Top margin of the first item. (Default: var(--space-xs))
+     * @cssprop --menu-shortcut-font-size - Font size of the keyboard shortcut label. (Default: max(0.75em, 9px))
+     */
     let {
         item,
         index,
@@ -11,11 +22,17 @@
         keyboardHasFocus,
         shape = 'default',
     }: {
+        /** The menu item data object. */
         item: Item;
+        /** The index of this item in the menu list. */
         index: number;
+        /** Callback when the mouse enters the item. */
         onmouseover?: (e: MouseEvent, item: Item, index: number) => void;
+        /** Callback when the item is selected. */
         onselect?: (item: Item, index: number) => void;
+        /** Whether keyboard navigation is active, suppressing mouse hover styles. */
         keyboardHasFocus?: boolean;
+        /** The border-radius shape of the item. */
         shape?: 'default' | 'rounded' | 'pill';
     } = $props();
 
@@ -104,20 +121,19 @@
     li .Item,
     li .Header,
     li .Text {
-        font-size: var(--font-size, 0.9em);
+        font-size: var(--menu-item-font-size, var(--font-size-sm));
         text-align: left;
-        padding-block: 0.5rem;
-        padding-inline: 1rem;
+        padding-block: var(--menu-item-padding-block, var(--space-xs));
+        padding-inline: var(--menu-item-padding-inline, var(--space-md));
         display: inline-flex;
         align-items: center;
         justify-content: space-between;
         width: 100%;
-        color: inherit;
         text-decoration: none;
         color: var(--color);
-        --inset-block: 0.5rem;
-        --inset-inline: 1rem;
-        border-radius: none;
+        --inset-block: var(--menu-item-padding-block, var(--space-xs));
+        --inset-inline: var(--menu-item-padding-inline, var(--space-md));
+        border-radius: 0;
         white-space: nowrap;
     }
 
@@ -128,7 +144,7 @@
     }
 
     li .Header {
-        font-weight: 600;
+        font-weight: var(--font-weight-medium);
     }
 
     li:not(.keyboardHasFocus) .Item:not(.Custom):hover,
@@ -146,7 +162,7 @@
     }
 
     li .Item span.Shortcut {
-        font-size: max(0.75em, 9px);
+        font-size: var(--menu-shortcut-font-size, max(0.75em, 9px));
         text-align: right;
         color: var(--menu-text-color-subtle);
         white-space: nowrap;
@@ -157,23 +173,23 @@
     }
 
     li.divider {
-        padding-block: 0.5rem;
+        padding-block: var(--menu-item-padding-block, var(--space-xs));
     }
 
     hr {
         display: block;
         border: none;
         margin: 0;
-        border-top: 1px solid var(--menu-border-color);
+        border-top: var(--menu-border-size) var(--menu-border-style) var(--menu-border-color);
     }
 
     li:first-child[data-type="item"] {
-        margin-block-start: var(--menu-item-margin, 0.5rem);
+        margin-block-start: var(--menu-item-margin, var(--space-xs));
     }
 
-    @media (pointer: none) {
+    @media (pointer: coarse) {
         li .Item span.Shortcut {
             display: none;
-        }        
+        }
     }
 </style>

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

@@ -1,10 +1,16 @@
 import type { MenuItem as Item } from "./MenuTypes.js";
 type $$ComponentProps = {
+    /** The menu item data object. */
     item: Item;
+    /** The index of this item in the menu list. */
     index: number;
+    /** Callback when the mouse enters the item. */
     onmouseover?: (e: MouseEvent, item: Item, index: number) => void;
+    /** Callback when the item is selected. */
     onselect?: (item: Item, index: number) => void;
+    /** Whether keyboard navigation is active, suppressing mouse hover styles. */
     keyboardHasFocus?: boolean;
+    /** The border-radius shape of the item. */
     shape?: 'default' | 'rounded' | 'pill';
 };
 declare const MenuItem: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/Modal.svelte

@@ -5,30 +5,20 @@
     import type { ModalButton } from "./ModalTypes.js";
 
     /**
-     * A modal component using the native `<dialog>` element.
-     * 
-     * **Pattern A: Trigger-based**
-     * ```svelte
-     * <Modal {trigger} {content} />
-     * ```
-     * 
-     * **Pattern B: Controlled state**
-     * ```svelte
+     * @description
+     * A modal component using the native `<dialog>` element. Supports trigger-based, controlled, and auto-show patterns.
+     * Uses modal tokens for styling. The `contained` prop can be set via context.
+     * @cssprop --modal-width - Width of the modal. (Default: fit-content)
+     * @cssprop --modal-min-width - Minimum width. (Default: auto)
+     * @cssprop --modal-max-width - Maximum width. (Default: 40rem)
+     * @cssprop --modal-max-height - Maximum height. (Default: 80svh)
+     * @example
      * <Modal bind:open={showModal}>
      *     {#snippet content(close)}
      *         <p>Modal content</p>
+     *         <button onclick={close}>Close</button>
      *     {/snippet}
      * </Modal>
-     * ```
-     * 
-     * **Pattern C: Auto-show (no trigger)**
-     * ```svelte
-     * {#if shouldShow}
-     *     <Modal open onclose={() => shouldShow = false}>
-     *         {#snippet content(close)}...{/snippet}
-     *     </Modal>
-     * {/if}
-     * ```
      */
     let {
         open = $bindable(false),
@@ -241,6 +231,31 @@
     dialog.Modal[open] {
         display: grid;
         grid-template-rows: 1fr auto;
+        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.Modal[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.Modal[open] {
+            opacity: 0;
+            translate: 0 var(--space-xs);
+        }
+        dialog.Modal[open]::backdrop {
+            opacity: 0;
+        }
     }
 
     dialog.Modal.contained {
@@ -306,7 +321,8 @@
     }
 
     @media (prefers-reduced-motion: reduce) {
-        dialog.Modal {
+        dialog.Modal,
+        dialog.Modal::backdrop {
             transition: none;
         }
     }