lutra 0.1.68 → 0.1.70

package/dist/form/Form.svelte

@@ -12,6 +12,30 @@
 	import { getIndividualValidators, parseFormIssues } from "./form.js";
 	import { useForm } from "./client.svelte.js";
 
+    /**
+     * @description
+     * The root form component. Wraps SvelteKit's `enhance` for progressive enhancement,
+     * integrates with Zod-based validation via Bodyguard, and provides layout token
+     * overrides for all child form sections, fields and actions.
+     *
+     * @cssprop --form-action-gap -- Gap between action buttons.
+     * @cssprop --form-field-gap -- Gap between fields in a section.
+     * @cssprop --form-label-gap -- Gap between label and input.
+     * @cssprop --form-title-gap -- Gap within a section title.
+     * @cssprop --form-section-gap -- Gap between sections.
+     * @cssprop --form-padding-block -- Block padding for contained sections.
+     * @cssprop --form-padding-inline -- Inline padding for contained sections.
+     *
+     * @example
+     * <Form form={data.form} action="?/save">
+     *   <FormSection title="Profile">
+     *     <Input name="name" label="Name" />
+     *   </FormSection>
+     *   <FormActions>
+     *     <Button type="submit">Save</Button>
+     *   </FormActions>
+     * </Form>
+     */
     let {
         name = 'form',
         form: _form,
@@ -35,15 +59,25 @@
         paddingBlock,
         paddingInline,
     }: {
+        /** The key under which the form data is returned in the action result. */
         name?: string;
+        /** The Lutra form object from the server load function. */
         form?: LutraForm<any>;
+        /** Bindable reference to the underlying `<form>` element. */
         formEl?: HTMLFormElement | null;
+        /** The form action URL. */
         action?: string;
+        /** The form encoding type. */
         enctype?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain";
+        /** The HTTP method. */
         method?: "GET" | "POST";
+        /** Callback invoked before the form is submitted. Can cancel submission. */
         beforesubmit?: BeforeSubmitFn;
+        /** Whether the form should span the full width. */
         fullWidth?: boolean;
+        /** Whether to reset fields after a successful update. */
         resetOnUpdate?: boolean;
+        /** Callback invoked with the action result after submission. */
         onresult?: (args: {
             formData: FormData;
             formElement: HTMLFormElement;
@@ -54,16 +88,27 @@
                 invalidateAll?: boolean | undefined;
             } | undefined) => void;
         }) => void;
+        /** Form content. */
         children: Snippet;
+        /** Whether the form sections should be contained (bordered). */
         contained?: boolean;
+        /** General spacing override. */
         spacing?: string;
+        /** Override for `--form-action-gap`. */
         actionGap?: string;
+        /** Override for `--form-field-gap`. */
         fieldGap?: string;
+        /** Override for `--form-label-gap`. */
         labelGap?: string;
+        /** Override for `--form-title-gap`. */
         titleGap?: string;
+        /** Override for `--form-section-gap`. */
         sectionGap?: string;
+        /** Shorthand override for both `--form-padding-block` and `--form-padding-inline`. */
         padding?: string;
+        /** Override for `--form-padding-block`. */
         paddingBlock?: string;
+        /** Override for `--form-padding-inline`. */
         paddingInline?: string;
     } = $props();
 
@@ -85,7 +130,6 @@
     const bodyguard = new Bodyguard();
 
     function setFormIssuesAndFields(issues: any, fields: any) {
-        console.log('setFormIssuesAndFields', issues, fields)
         if(form) {
             form.issues = issues;
             form.fields = fields;
@@ -126,6 +170,7 @@
     };
 
     const style = `
+        --fcc: ${contained ? 1 : 0};
         ${actionGap ? `--form-action-gap: ${actionGap};` : ''}
         ${fieldGap ? `--form-field-gap: ${fieldGap};` : ''}
         ${labelGap ? `--form-label-gap: ${labelGap};` : ''}
@@ -146,75 +191,104 @@
 </script>
 
 <UiContent>
-    <form
-        {method}
-        {action}
-        {enctype}
-        style={style}
-        bind:this={formEl}
-        onchange={validate}
-        use:enhance={async ({ formElement, formData, action, cancel, submitter }) => {
-            // `formElement` is this `<form>` element
-            // `formData` is its `FormData` object that's about to be submitted
-            // `action` is the URL to which the form is posted
-            // calling `cancel()` will prevent the submission
-            // `submitter` is the `HTMLElement` that caused the form to be submitted
-            if(form) form.state = 'loading';
-            //await Promise.resolve(beforesubmit(form));
-            if(beforesubmit) await Promise.resolve(beforesubmit({ form: formElement, data: formData, cancel: () => {
-                if(form) form.state = 'error';
-                cancel();
-            }}));
-            for(const { id, fn } of beforesubmitFunctions) {
-                await Promise.resolve(fn({ form: formElement, data: formData, cancel: () => {
+    <div class="FormContainer">
+        <form
+            {method}
+            {action}
+            {enctype}
+            style={style}
+            bind:this={formEl}
+            onchange={validate}
+            use:enhance={async ({ formElement, formData, action, cancel, submitter }) => {
+                // `formElement` is this `<form>` element
+                // `formData` is its `FormData` object that's about to be submitted
+                // `action` is the URL to which the form is posted
+                // calling `cancel()` will prevent the submission
+                // `submitter` is the `HTMLElement` that caused the form to be submitted
+                if(form) form.state = 'loading';
+                //await Promise.resolve(beforesubmit(form));
+                if(beforesubmit) await Promise.resolve(beforesubmit({ form: formElement, data: formData, cancel: () => {
                     if(form) form.state = 'error';
                     cancel();
                 }}));
-            }
-            console.log('form state', form?.state);
-            return async (opts) => {
-                const { result, update } = opts;
-                // `result` is an `ActionResult` object
-                // `update` is a function which triggers the default logic that would be triggered if this callback wasn't set
-                console.log('form result', opts);
-                if(onresult) {
-                    console.log('calling onresult', opts);
-                    onresult(opts);
+                for(const { id, fn } of beforesubmitFunctions) {
+                    await Promise.resolve(fn({ form: formElement, data: formData, cancel: () => {
+                        if(form) form.state = 'error';
+                        cancel();
+                    }}));
                 }
-                const resultForm = result.type !== "redirect" && result.type !== "error" ? result?.data![name] : null;
-                console.log('resultForm', resultForm, form);
-                if(result.type === "success") {
-                    if(resultForm && form) {
-                        form.valid = Object.assign({ valid: false }, resultForm).valid ?? false;
+                return async (opts) => {
+                    const { result, update } = opts;
+                    if(onresult) {
+                        onresult(opts);
                     }
-                    if(form) form.state = 'success';
-                    console.log('form state', form?.state, resetOnUpdate, opts);
-                    update({ reset: !!resetOnUpdate });
-                } else if(result.type === "failure") {
-                    console.log('FAILURE', opts);
-                    if(resultForm && form) {
-                        console.log('setting form issues and fields')
-                        setFormIssuesAndFields(
-                            Object.assign({ issues: [] }, resultForm).issues, // Have to assign to avoid type error as we cant use `as` here
-                            Object.assign({ fields: [] }, resultForm).fields,
-                        );
+                    const resultForm = result.type !== "redirect" && result.type !== "error" ? result?.data![name] : null;
+                    if(result.type === "success") {
+                        if(resultForm && form) {
+                            form.valid = Object.assign({ valid: false }, resultForm).valid ?? false;
+                        }
+                        if(form) form.state = 'success';
+                        update({ reset: !!resetOnUpdate });
+                    } else if(result.type === "failure") {
+                        if(resultForm && form) {
+                            setFormIssuesAndFields(
+                                Object.assign({ issues: [] }, resultForm).issues, // Have to assign to avoid type error as we cant use `as` here
+                                Object.assign({ fields: [] }, resultForm).fields,
+                            );
+                        }
+                        if(form) form.state = 'error';
+                    } else if(result.type === "error") {
+                        console.error('[lutra] Error from form enhance call', result.error, opts);
+                        if(form) form.state = 'error';
+                    } else if(result.type === "redirect") {
+                        if(form) form.state = 'success';
+                        await goto(result.location);
                     }
-                    if(form) form.state = 'error';
-                } else if(result.type === "error") {
-                    console.error('[lutra] Error from form enhance call', result.error, opts);
-                    if(form) form.state = 'error';
-                } else if(result.type === "redirect") {
-                    console.log('redirect', opts);
-                    //window.location.href = result.location;
-                    if(form) form.state = 'success';
-                    await goto(result.location);
-                }
-            };
-        }}
-    >
-        {@render children()}
-    </form>
+                };
+            }}
+        >
+            {@render children()}
+        </form>
+    </div>
 </UiContent>
 
 <style>
+    .FormContainer {
+        container-type: inline-size;
+    }
+    form {
+        display: grid;
+        grid-template-columns: fit-content(20%) 1fr;
+        border: calc(var(--fcc) * var(--form-border-size)) var(--form-border-style) var(--form-border-color);
+        border-radius: calc(var(--fcc) * var(--form-border-radius));
+        --form-padding-block: var(--space-md);
+        --form-padding-inline: var(--space-md);
+        --form-section-gap: var(--space-md);
+    }
+    @container (min-width: 600px) {
+        form {
+            --form-padding-block: var(--space-lg);
+            --form-padding-inline: var(--space-lg);
+            --form-section-gap: var(--space-xl);
+        }
+    }
+    @container (min-width: 1000px) {
+        form {
+            --form-padding-block: var(--space-xl);
+            --form-padding-inline: var(--space-xl);
+            --form-section-gap: var(--space-xxl);
+        }
+    }
+    @container (min-width: 1400px) {
+        form {
+            --form-padding-block: var(--space-xxl);
+            --form-padding-inline: var(--space-xxl);
+            --form-section-gap: var(--space-xxxl);
+        }
+    }
+    @container (max-width: 800px) {
+        form {
+            grid-template-columns: 1fr;
+        }
+    }
 </style>

package/dist/form/Form.svelte.d.ts

@@ -2,15 +2,25 @@ import type { ActionResult } from "@sveltejs/kit";
 import type { Snippet } from "svelte";
 import type { BeforeSubmitFn, LutraForm } from "./types.js";
 type $$ComponentProps = {
+    /** The key under which the form data is returned in the action result. */
     name?: string;
+    /** The Lutra form object from the server load function. */
     form?: LutraForm<any>;
+    /** Bindable reference to the underlying `<form>` element. */
     formEl?: HTMLFormElement | null;
+    /** The form action URL. */
     action?: string;
+    /** The form encoding type. */
     enctype?: "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain";
+    /** The HTTP method. */
     method?: "GET" | "POST";
+    /** Callback invoked before the form is submitted. Can cancel submission. */
     beforesubmit?: BeforeSubmitFn;
+    /** Whether the form should span the full width. */
     fullWidth?: boolean;
+    /** Whether to reset fields after a successful update. */
     resetOnUpdate?: boolean;
+    /** Callback invoked with the action result after submission. */
     onresult?: (args: {
         formData: FormData;
         formElement: HTMLFormElement;
@@ -21,16 +31,27 @@ type $$ComponentProps = {
             invalidateAll?: boolean | undefined;
         } | undefined) => void;
     }) => void;
+    /** Form content. */
     children: Snippet;
+    /** Whether the form sections should be contained (bordered). */
     contained?: boolean;
+    /** General spacing override. */
     spacing?: string;
+    /** Override for `--form-action-gap`. */
     actionGap?: string;
+    /** Override for `--form-field-gap`. */
     fieldGap?: string;
+    /** Override for `--form-label-gap`. */
     labelGap?: string;
+    /** Override for `--form-title-gap`. */
     titleGap?: string;
+    /** Override for `--form-section-gap`. */
     sectionGap?: string;
+    /** Shorthand override for both `--form-padding-block` and `--form-padding-inline`. */
     padding?: string;
+    /** Override for `--form-padding-block`. */
     paddingBlock?: string;
+    /** Override for `--form-padding-inline`. */
     paddingInline?: string;
 };
 declare const Form: import("svelte").Component<$$ComponentProps, {}, "formEl">;

package/dist/form/FormActions.svelte

@@ -2,20 +2,38 @@
 	import StringOrSnippet from "../util/StringOrSnippet.svelte";
     import { setContext, type Snippet } from "svelte";
 
+    /**
+     * @description
+     * Action bar for form buttons. Renders at the bottom of a form with configurable
+     * alignment. When the form is contained, inherits background and padding from
+     * `--form-background-actions` via the `--fcc` multiplier pattern.
+     *
+     * @example
+     * <FormActions>
+     *   <Button type="submit">Save</Button>
+     * </FormActions>
+     * <FormActions align="justified" info="Changes are saved automatically.">
+     *   <Button type="submit">Save</Button>
+     *   <Button kind="secondary" href="/cancel">Cancel</Button>
+     * </FormActions>
+     */
     let {
         align = 'end',
         children,
         info,
     }: {
+        /** Alignment of the action buttons. */
         align?: 'justified' | 'start' | 'center' | 'end' | 'full';
+        /** Action buttons and other content. */
         children: Snippet;
+        /** Optional info text displayed alongside the action buttons. */
         info?: string | Snippet;
     } = $props();
 
     setContext('form.actions.align', align);
 </script>
 
-<div class="FormActions {align}" class:hasInfo={!!info}>
+<div class="FormActions {align}">
     {#if info}
         <div class="Info">
             <StringOrSnippet content={info} />
@@ -29,7 +47,7 @@
 <style>
     .FormActions {
         display: grid;
-        background: color-mix(in srgb, var(--form-background-actions) calc(var(--fcc) * 100%), transparent);
+        background: color-mix(in oklch, var(--form-background-actions) calc(var(--fcc) * 100%), transparent);
         padding: calc(var(--space-md) * var(--fcc)) calc(var(--space-xl) * var(--fcc));
         grid-column: 1 / -1;
         grid-template-columns: subgrid;
@@ -57,7 +75,7 @@
         justify-content: end;
         grid-column: 1 / -1;
     }
-    .FormActions.hasInfo .Actions {
+    .FormActions:has(.Info) .Actions {
         grid-column: 2 / -1;
     }
     .FormActions.full .Actions {

package/dist/form/FormActions.svelte.d.ts

@@ -1,7 +1,10 @@
 import { type Snippet } from "svelte";
 type $$ComponentProps = {
+    /** Alignment of the action buttons. */
     align?: 'justified' | 'start' | 'center' | 'end' | 'full';
+    /** Action buttons and other content. */
     children: Snippet;
+    /** Optional info text displayed alongside the action buttons. */
     info?: string | Snippet;
 };
 declare const FormActions: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/form/FormSection.svelte

@@ -3,7 +3,21 @@
 
     /**
      * @description
-     * A field section is a group of related form elements.
+     * A section within a form, grouping related fields under an optional title and
+     * description. Uses CSS subgrid for alignment with the parent form layout and
+     * responds to `@container` queries to collapse into a single column at narrow widths.
+     *
+     * @cssprop --form-section-gap -- Gap between the title and content areas.
+     * @cssprop --form-title-gap -- Gap within the section title (title + description).
+     * @cssprop --form-field-gap -- Gap between fields in the content area.
+     * @cssprop --form-padding-block -- Block padding when the form is contained.
+     * @cssprop --form-padding-inline -- Inline padding when the form is contained.
+     *
+     * @example
+     * <FormSection title="Personal Information" description="Enter your details.">
+     *   <Input name="name" label="Name" />
+     *   <Input name="email" type="email" label="Email" />
+     * </FormSection>
      */
     let {
         title,
@@ -53,12 +67,11 @@
     .FormSectionTitle {
         display: flex;
         flex-direction: column;
-        background-color: var(--base);
         gap: var(--form-title-gap, var(--space-md));
         text-wrap: balance;
     }
     .FormSection:not(:first-child) {
-        border-top: calc(var(--fcc) * var(--border-size)) var(--border-style) var(--border-color);
+        border-top: calc(var(--fcc) * var(--form-border-size)) var(--form-border-style) var(--form-border-color);
     }
     .FormSectionContent {
         display: grid;
@@ -67,27 +80,16 @@
     .FormSection.noTitle .FormSectionContent {
         grid-column: 1 / -1;
     }
-    @media(max-width: 1280px) {
-        .FormSection {
-            padding: var(--space-xl);
-            gap: var(--space-md);
-        }
-        .FormSectionTitle {
-            gap: var(--space-xs);
-            padding-block-end: var(--space-md);
-        }
-    }
-    @media(max-width: 640px) {
+    @container (max-width: 800px) {
         .FormSection {
-            padding: var(--space-xl);
-            gap: var(--space-md);
+            padding-block: calc(var(--fcc) * var(--form-padding-block));
+            padding-inline: calc(var(--fcc) * var(--form-padding-inline));
+            gap: var(--form-section-gap, var(--space-md));
         }
         .FormSectionTitle {
-            gap: var(--space-xs);
-            padding-block-end: var(--space-md);
+            gap: var(--form-title-gap);
+            padding-block-end: var(--form-title-padding-block-end);
         }
-    }
-    @container (max-width: 800px) {
         .FormSectionTitle,
         .FormSectionContent {
             grid-column: 1 / -1;

package/dist/form/ImageUpload.svelte

@@ -9,6 +9,23 @@
     const imageCompression: ImageCompressionFn = (imageCompressionModule as unknown as { default?: ImageCompressionFn }).default ?? imageCompressionModule as unknown as ImageCompressionFn;
 	import { addToast } from "../components/toasts.svelte.js";
 
+    /**
+     * @description
+     * An image upload component with client-side compression, progress indicator and
+     * optional remove button. Supports square, circle and banner display shapes.
+     * Uploads to a presigned URL via `PUT`.
+     *
+     * @cssprop --max-image-width -- Maximum width of the image preview (used in the grid layout).
+     *
+     * @example
+     * <ImageUpload
+     *   uploadUrl="/api/upload"
+     *   name="avatar"
+     *   button="Upload"
+     *   shape="circle"
+     *   src={user.avatarUrl}
+     * />
+     */
     let {
         src,
         uploadUrl,
@@ -25,19 +42,33 @@
         onFile,
         children,
     }: {
+        /** Current image source URL. */
         src?: string | null;
+        /** The presigned URL to upload the image to. */
         uploadUrl: string;
+        /** The form field name for the resulting URL value. */
         name: string;
+        /** HTML id for the file input. */
         id?: string;
+        /** Title used in the alt text of the preview image. */
         title?: string;
+        /** Label for the upload button. */
         button: string;
+        /** Maximum file size in bytes before compression is applied. */
         maxSize?: number;
+        /** Maximum compressed file size in megabytes. */
         compressSize?: number;
+        /** Maximum compressed image width in pixels. */
         compressMaxWidth?: number;
+        /** Accepted MIME types for the file input. */
         accept?: string;
+        /** Whether a remove button is shown. */
         removable?: boolean;
+        /** Display shape of the image preview. */
         shape?: 'square' | 'circle' | 'banner';
+        /** Callback invoked with the selected file before upload. */
         onFile?: (file: File) => void;
+        /** Optional additional content rendered below the actions. */
         children?: Snippet;
     } = $props();
 
@@ -63,8 +94,6 @@
                 useWebWorker: true,
                 onProgress: (progress: number) => resizeProgress = progress,
             });
-            console.log('compressedFile instanceof Blob', compressedFile instanceof Blob); // true
-            console.log(`compressedFile size ${compressedFile.size / 1024 / 1024} MB`); // smaller than maxSizeMB
             uploadState = 'uploading';
 
             const response = await fetch(uploadUrl, {
@@ -79,15 +108,10 @@
                 addToast({ content: 'Something went wrong. Please try again.', autoClose: 3000 })
                 cancel();
             }
-            //src = new URL(response.url).href.split('?')[0];
-            console.log('setting', name, new URL(response.url).href.split('?')[0]);
             const imgUrl = new URL(response.url).href.split('?')[0];
             data.set(name, imgUrl);
             src = imgUrl;
-            console.log('response', response, response.url);
-            console.log('data', data.forEach((v, k) => console.log(k, v)));
         } catch(err) {
-            console.error('error', err);
             addToast({ content: 'Something went wrong. Please try again.', autoClose: 3000 })
             cancel();
         }
@@ -141,7 +165,7 @@
 </script>
 
 <div class="ImageUpload {shape}">
-    <div class="Image" class:hasSrc={!!src}>
+    <div class="Image">
         {#if src}
             <img src={src} alt="{title} logo" />
         {/if}
@@ -194,16 +218,16 @@
         display: grid;
         grid-template-columns: 1fr;
         align-items: center;
-        gap: 1rem;
+        gap: var(--space-md);
         container-type: inline-size;
     }
     .Image {
-        border: 1px solid var(--border-light);
+        border: var(--border-size-thin) solid var(--border-color-subtle);
         pointer-events: none;
         position: relative;
         display: none;
     }
-    .Image.hasSrc {
+    .Image:has(img) {
         display: block;
     }
     .Image img {
@@ -229,32 +253,29 @@
         height: 100%;
         width: 100%;
         object-fit: contain;
-        padding: 1rem;
+        padding: var(--space-md);
         text-align: center;
-        border: 1px dashed var(--border-color);
-        border-radius: var(--border-radius);
+        border: var(--border-size-thin) dashed var(--border-color);
+        border-radius: var(--border-radius-base);
     }
     .Loading {
         position: absolute;
-        top: 0;
-        left: 0;
-        right: 0;
-        bottom: 0;
+        inset: 0;
         z-index: 5;
-        backdrop-filter: blur(5px);
-        background: var(--bg-overlay);
+        backdrop-filter: var(--scrim-backdrop-filter);
+        background: var(--scrim-background);
         display: flex;
         align-items: center;
         justify-content: center;
         flex-direction: column;
-        gap: 1rem;
-        padding: 1rem;
+        gap: var(--space-md);
+        padding: var(--space-md);
     }
     input {
         display: none;
     }
     .error {
-        margin-top: 0.75rem;
+        margin-block-start: var(--space-sm);
     }
     .ImageUpload.banner {
         grid-template-areas: "image";
@@ -266,7 +287,6 @@
         overflow: hidden;
         object-fit: cover;
         height: 15rem;
-        aspect-ratio: initial !important;
     }
     .ImageUpload.banner .Image img {
         object-fit: cover;
@@ -276,28 +296,28 @@
         grid-area: image;
         flex-direction: column;
         justify-content: center;
-        padding: 1rem;
+        padding: var(--space-md);
     }
     .ImageUpload.banner:hover .ImageUploadActions {
-        background: var(--bg-overlay);
+        background: var(--scrim-background);
     }
     .ImageUploadActions {
         display: grid;
         grid-template-columns: 1fr 1fr;
-        gap: 0.75rem;
+        gap: var(--space-sm);
         align-items: start;
     }
     @container (min-width: 320px) {
         .ImageUpload:not(.banner) {
             grid-template-columns: minmax(auto, var(--max-image-width)) 1fr;
-            gap: 2rem;
+            gap: var(--space-xl);
         }
         .ImageUpload.banner .ImageUploadActions {
-            padding: 3rem;
+            padding: var(--space-xxl);
         }
         .ImageUploadActions {
             grid-template-columns: 1fr;
-            gap: 1rem;
+            gap: var(--space-md);
         }
     }
 </style>