@tanglemedia/svelte-starter-ui-shadcn 0.1.0 → 0.2.0

package/dist/lib/components/extended/inline-edit/inline-edit-input.svelte

@@ -0,0 +1,125 @@
+<script lang="ts">
+  import Input from "../../ui/input/input.svelte";
+  import { cn, type WithElementRef } from "../../utils.js";
+
+  import { useInlineEditContext } from "./inline-edit.context.svelte.js";
+
+  import type { Snippet } from "svelte";
+  import type {
+    HTMLInputAttributes,
+    HTMLInputTypeAttribute,
+  } from "svelte/elements";
+
+  type InputType = Exclude<HTMLInputTypeAttribute, "file">;
+  type InlineEditContext = ReturnType<typeof useInlineEditContext>;
+
+  type Props = WithElementRef<
+    Omit<HTMLInputAttributes, "children" | "files" | "type" | "value">,
+    HTMLInputElement
+  > & {
+    type?: InputType;
+    containerClass?: string;
+    addon?: Snippet<[InlineEditContext]>;
+    children?: Snippet<[InlineEditContext]>;
+  };
+
+  let {
+    ref = $bindable(null),
+    type = "text",
+    containerClass,
+    addon,
+    children,
+    class: className,
+    id,
+    readonly,
+    onblur,
+    onkeydown,
+    "aria-label": ariaLabel,
+    "aria-invalid": ariaInvalid,
+    "aria-describedby": ariaDescribedBy,
+    "aria-busy": ariaBusy,
+    "data-slot": dataSlot = "inline-edit-input",
+    ...restProps
+  }: Props = $props();
+
+  const inlineEdit = useInlineEditContext();
+  let detachInput: (() => void) | null = null;
+
+  /** Returns the currently bound input for Svelte's function binding. */
+  function getInput(): HTMLElement | null {
+    return ref;
+  }
+
+  /** Keeps the consumer ref and shared focus target synchronized with the rendered input. */
+  function setInput(node: HTMLElement | null): void {
+    detachInput?.();
+    detachInput = null;
+    ref = node as HTMLInputElement | null;
+
+    if (ref) {
+      detachInput = inlineEdit.attachInput(ref);
+    }
+  }
+
+  /** Commits the draft after allowing a consumer blur handler to prevent the default behavior. */
+  function handleBlur(
+    event: FocusEvent & { currentTarget: EventTarget & HTMLInputElement },
+  ): void {
+    onblur?.(event);
+
+    if (event.defaultPrevented) {
+      return;
+    }
+
+    const nextTarget = event.relatedTarget;
+    if (
+      nextTarget instanceof Node &&
+      event.currentTarget.parentElement?.contains(nextTarget)
+    ) {
+      return;
+    }
+
+    void inlineEdit.commit();
+  }
+
+  /** Applies keyboard editing behavior after invoking the consumer's key handler. */
+  function handleKeydown(
+    event: KeyboardEvent & { currentTarget: EventTarget & HTMLInputElement },
+  ): void {
+    onkeydown?.(event);
+
+    if (event.defaultPrevented) {
+      return;
+    }
+
+    inlineEdit.handleKeydown(event);
+  }
+</script>
+
+{#if inlineEdit.editing}
+  <span
+    data-slot="inline-edit-input-container"
+    class={cn("relative inline-flex w-full items-center", containerClass)}
+  >
+    <Input
+      bind:ref={getInput, setInput}
+      bind:value={inlineEdit.draft}
+      {type}
+      id={id ?? inlineEdit.inputId}
+      data-slot={dataSlot}
+      data-status={inlineEdit.status}
+      class={className}
+      readonly={readonly === true || inlineEdit.saving}
+      aria-label={ariaLabel ?? inlineEdit.label}
+      aria-invalid={ariaInvalid ?? (inlineEdit.error ? "true" : undefined)}
+      aria-describedby={ariaDescribedBy ??
+        (inlineEdit.error ? inlineEdit.errorId : undefined)}
+      aria-busy={ariaBusy ?? inlineEdit.saving}
+      onblur={handleBlur}
+      onkeydown={handleKeydown}
+      {...restProps}
+    />
+    {@render addon?.(inlineEdit)}
+    {@render children?.(inlineEdit)}
+  </span>
+{/if}

package/dist/lib/components/extended/inline-edit/inline-edit-input.svelte.d.ts

@@ -0,0 +1,15 @@
+import { type WithElementRef } from "../../utils.js";
+import { useInlineEditContext } from "./inline-edit.context.svelte.js";
+import type { Snippet } from "svelte";
+import type { HTMLInputAttributes, HTMLInputTypeAttribute } from "svelte/elements";
+type InputType = Exclude<HTMLInputTypeAttribute, "file">;
+type InlineEditContext = ReturnType<typeof useInlineEditContext>;
+type Props = WithElementRef<Omit<HTMLInputAttributes, "children" | "files" | "type" | "value">, HTMLInputElement> & {
+    type?: InputType;
+    containerClass?: string;
+    addon?: Snippet<[InlineEditContext]>;
+    children?: Snippet<[InlineEditContext]>;
+};
+declare const InlineEditInput: import("svelte").Component<Props, {}, "ref">;
+type InlineEditInput = ReturnType<typeof InlineEditInput>;
+export default InlineEditInput;

package/dist/lib/components/extended/inline-edit/inline-edit-root.svelte

@@ -0,0 +1,86 @@
+<script lang="ts">
+  import { onDestroy } from "svelte";
+
+  import { cn, type WithElementRef } from "../../utils.js";
+
+  import { setInlineEditContext } from "./inline-edit.context.svelte.js";
+  import { InlineEditState } from "./inline-edit-state.class.svelte.js";
+
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import type {
+    InlineEditCommit,
+    InlineEditNormalize,
+    InlineEditValidate,
+  } from "./inline-edit-state.class.svelte.js";
+
+  type Props = WithElementRef<
+    Omit<HTMLAttributes<HTMLSpanElement>, "children">,
+    HTMLSpanElement
+  > & {
+    value: string;
+    label: string;
+    onCommit: InlineEditCommit;
+    validate?: InlineEditValidate;
+    normalize?: InlineEditNormalize;
+    errorMessage?: string;
+    successDuration?: number;
+    children?: Snippet<[InlineEditState]>;
+  };
+
+  let {
+    ref = $bindable(null),
+    value = $bindable(),
+    label,
+    onCommit,
+    validate,
+    normalize,
+    errorMessage,
+    successDuration,
+    children,
+    class: className,
+    "data-slot": dataSlot = "inline-edit-root",
+    ...restProps
+  }: Props = $props();
+
+  const instanceId = $props.id();
+  const state = setInlineEditContext(
+    new InlineEditState({
+      id: instanceId,
+      getLabel: () => label,
+      getValue: () => value,
+      setValue: (nextValue) => {
+        value = nextValue;
+      },
+      onCommit: (nextValue) => onCommit(nextValue),
+      validate: (nextValue) => validate?.(nextValue),
+      normalize: (nextValue) => normalize?.(nextValue) ?? nextValue,
+      getErrorMessage: () => errorMessage,
+      getSuccessDuration: () => successDuration,
+    }),
+  );
+
+  onDestroy(() => state.destroy());
+
+  /** Exposes the root element through the optional bindable ref. */
+  function attachRef(node: HTMLSpanElement): () => void {
+    ref = node;
+
+    return () => {
+      if (ref === node) {
+        ref = null;
+      }
+    };
+  }
+</script>
+
+<span
+  {@attach attachRef}
+  data-slot={dataSlot}
+  data-state={state.editing ? "editing" : "viewing"}
+  data-status={state.status}
+  class={cn("inline-flex flex-col items-start", className)}
+  {...restProps}
+>
+  {@render children?.(state)}
+</span>

package/dist/lib/components/extended/inline-edit/inline-edit-root.svelte.d.ts

@@ -0,0 +1,18 @@
+import { type WithElementRef } from "../../utils.js";
+import { InlineEditState } from "./inline-edit-state.class.svelte.js";
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+import type { InlineEditCommit, InlineEditNormalize, InlineEditValidate } from "./inline-edit-state.class.svelte.js";
+type Props = WithElementRef<Omit<HTMLAttributes<HTMLSpanElement>, "children">, HTMLSpanElement> & {
+    value: string;
+    label: string;
+    onCommit: InlineEditCommit;
+    validate?: InlineEditValidate;
+    normalize?: InlineEditNormalize;
+    errorMessage?: string;
+    successDuration?: number;
+    children?: Snippet<[InlineEditState]>;
+};
+declare const InlineEditRoot: import("svelte").Component<Props, {}, "ref" | "value">;
+type InlineEditRoot = ReturnType<typeof InlineEditRoot>;
+export default InlineEditRoot;

package/dist/lib/components/extended/inline-edit/inline-edit-state.class.svelte.d.ts

@@ -0,0 +1,53 @@
+export type InlineEditStatus = "idle" | "saving" | "saved";
+export type InlineEditCommit = (value: string) => Promise<string | void>;
+export type InlineEditValidate = (value: string) => string | null | undefined;
+export type InlineEditNormalize = (value: string) => string;
+export type InlineEditStateOptions = {
+    id: string;
+    getLabel: () => string;
+    getValue: () => string;
+    setValue: (value: string) => void;
+    onCommit: InlineEditCommit;
+    validate?: InlineEditValidate;
+    normalize?: InlineEditNormalize;
+    getErrorMessage?: () => string | undefined;
+    getSuccessDuration?: () => number | undefined;
+};
+/**
+ * Coordinates editable text state, validation, persistence feedback, and input focus for an
+ * `InlineEdit` component tree.
+ */
+export declare class InlineEditState {
+    #private;
+    readonly errorId: string;
+    readonly inputId: string;
+    draft: string;
+    editing: boolean;
+    error: string | null;
+    status: InlineEditStatus;
+    saving: boolean;
+    saved: boolean;
+    /** Creates state backed by getter and setter callbacks from the root component. */
+    constructor(options: InlineEditStateOptions);
+    /** Returns the current accessible label supplied by the root component. */
+    get label(): string;
+    /** Returns the current committed value supplied by the root component. */
+    get value(): string;
+    /** Opens the editor and focuses its input with the committed value selected. */
+    begin: () => Promise<void>;
+    /** Restores the committed value and closes the editor unless a save is in progress. */
+    cancel: () => void;
+    /** Replaces the editable draft and clears any error associated with the previous text. */
+    setDraft: (value: string) => void;
+    /**
+     * Validates and persists the draft or supplied value, then updates the bound value.
+     * This invokes the consumer-provided asynchronous commit callback.
+     */
+    commit: (value?: string) => Promise<void>;
+    /** Applies the editor's Enter-to-save and Escape-to-cancel keyboard behavior. */
+    handleKeydown: (event: KeyboardEvent) => void;
+    /** Tracks the mounted input used for selection, blur, and failed-save focus recovery. */
+    attachInput: (input: HTMLInputElement) => (() => void);
+    /** Cancels pending saved-feedback work when the root component is destroyed. */
+    destroy: () => void;
+}

package/dist/lib/components/extended/inline-edit/inline-edit-state.class.svelte.js

@@ -0,0 +1,161 @@
+import { tick } from "svelte";
+const DEFAULT_ERROR_MESSAGE = "Could not save changes";
+const DEFAULT_SUCCESS_DURATION = 3000;
+/**
+ * Coordinates editable text state, validation, persistence feedback, and input focus for an
+ * `InlineEdit` component tree.
+ */
+export class InlineEditState {
+    errorId;
+    inputId;
+    draft = $state("");
+    editing = $state(false);
+    error = $state(null);
+    status = $state("idle");
+    saving = $derived(this.status === "saving");
+    saved = $derived(this.status === "saved");
+    #input = $state(null);
+    #options;
+    #savedTimeout = null;
+    /** Creates state backed by getter and setter callbacks from the root component. */
+    constructor(options) {
+        this.#options = options;
+        this.inputId = `${options.id}-input`;
+        this.errorId = `${options.id}-error`;
+        this.draft = options.getValue();
+    }
+    /** Returns the current accessible label supplied by the root component. */
+    get label() {
+        return this.#options.getLabel();
+    }
+    /** Returns the current committed value supplied by the root component. */
+    get value() {
+        return this.#options.getValue();
+    }
+    /** Opens the editor and focuses its input with the committed value selected. */
+    begin = async () => {
+        this.#clearSaved();
+        this.draft = this.value;
+        this.error = null;
+        this.editing = true;
+        await this.#focus();
+    };
+    /** Restores the committed value and closes the editor unless a save is in progress. */
+    cancel = () => {
+        if (this.saving) {
+            return;
+        }
+        this.draft = this.value;
+        this.error = null;
+        this.editing = false;
+    };
+    /** Replaces the editable draft and clears any error associated with the previous text. */
+    setDraft = (value) => {
+        this.draft = value;
+        this.error = null;
+    };
+    /**
+     * Validates and persists the draft or supplied value, then updates the bound value.
+     * This invokes the consumer-provided asynchronous commit callback.
+     */
+    commit = async (value) => {
+        if (!this.editing || this.saving) {
+            return;
+        }
+        if (value !== undefined) {
+            this.setDraft(value);
+        }
+        const nextValue = this.#options.normalize?.(this.draft) ?? this.draft;
+        const validationError = this.#options.validate?.(nextValue) ?? null;
+        if (validationError) {
+            this.error = validationError;
+            await this.#focus();
+            return;
+        }
+        if (nextValue === this.value) {
+            this.draft = this.value;
+            this.error = null;
+            this.editing = false;
+            return;
+        }
+        this.#clearSaved();
+        this.error = null;
+        this.status = "saving";
+        try {
+            const committedValue = (await this.#options.onCommit(nextValue)) ?? nextValue;
+            this.#options.setValue(committedValue);
+            this.draft = committedValue;
+            this.editing = false;
+            this.#showSaved();
+        }
+        catch (error) {
+            this.status = "idle";
+            this.error = this.#getErrorMessage(error);
+            await this.#focus();
+        }
+    };
+    /** Applies the editor's Enter-to-save and Escape-to-cancel keyboard behavior. */
+    handleKeydown = (event) => {
+        if (event.isComposing || this.saving) {
+            return;
+        }
+        if (event.key === "Escape") {
+            event.preventDefault();
+            this.cancel();
+            return;
+        }
+        if (event.key === "Enter") {
+            event.preventDefault();
+            this.#input?.blur();
+        }
+    };
+    /** Tracks the mounted input used for selection, blur, and failed-save focus recovery. */
+    attachInput = (input) => {
+        this.#input = input;
+        return () => {
+            if (this.#input === input) {
+                this.#input = null;
+            }
+        };
+    };
+    /** Cancels pending saved-feedback work when the root component is destroyed. */
+    destroy = () => {
+        if (this.#savedTimeout === null) {
+            return;
+        }
+        clearTimeout(this.#savedTimeout);
+        this.#savedTimeout = null;
+    };
+    /** Focuses and selects the input after Svelte has rendered it. */
+    async #focus() {
+        await tick();
+        this.#input?.focus();
+        this.#input?.select();
+    }
+    /** Clears saved feedback without interrupting an in-flight save. */
+    #clearSaved() {
+        if (this.#savedTimeout !== null) {
+            clearTimeout(this.#savedTimeout);
+            this.#savedTimeout = null;
+        }
+        if (this.status === "saved") {
+            this.status = "idle";
+        }
+    }
+    /** Shows saved feedback for the configured duration. */
+    #showSaved() {
+        this.#clearSaved();
+        this.status = "saved";
+        this.#savedTimeout = setTimeout(() => {
+            this.status = "idle";
+            this.#savedTimeout = null;
+        }, this.#options.getSuccessDuration?.() ?? DEFAULT_SUCCESS_DURATION);
+    }
+    /** Returns a useful user-facing message for a rejected commit. */
+    #getErrorMessage(error) {
+        if (error instanceof Error) {
+            return error.message;
+        }
+        return this.#options.getErrorMessage?.() ?? DEFAULT_ERROR_MESSAGE;
+    }
+}

package/dist/lib/components/extended/inline-edit/inline-edit-state.class.svelte.test.d.ts

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

package/dist/lib/components/extended/inline-edit/inline-edit-state.class.svelte.test.js

@@ -0,0 +1,115 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { InlineEditState } from "./inline-edit-state.class.svelte.js";
+afterEach(() => {
+    vi.useRealTimers();
+});
+describe("InlineEditState", () => {
+    it("normalizes a draft and stores the canonical committed value", async () => {
+        let value = "Original";
+        const onCommit = vi.fn(async () => "Canonical title");
+        const state = new InlineEditState({
+            id: "title",
+            getLabel: () => "Title",
+            getValue: () => value,
+            setValue: (nextValue) => {
+                value = nextValue;
+            },
+            onCommit,
+            normalize: (nextValue) => nextValue.trim(),
+        });
+        await state.begin();
+        state.setDraft("  Updated title  ");
+        await state.commit();
+        expect(onCommit).toHaveBeenCalledWith("Updated title");
+        expect(value).toBe("Canonical title");
+        expect(state.value).toBe("Canonical title");
+        expect(state.editing).toBe(false);
+        expect(state.status).toBe("saved");
+        state.destroy();
+    });
+    it("commits a supplied value for programmatic input addons", async () => {
+        let value = "Original";
+        const onCommit = vi.fn(async (nextValue) => nextValue);
+        const state = new InlineEditState({
+            id: "title",
+            getLabel: () => "Title",
+            getValue: () => value,
+            setValue: (nextValue) => {
+                value = nextValue;
+            },
+            onCommit,
+        });
+        await state.begin();
+        await state.commit("Generated title");
+        expect(onCommit).toHaveBeenCalledWith("Generated title");
+        expect(value).toBe("Generated title");
+        expect(state.draft).toBe("Generated title");
+        expect(state.editing).toBe(false);
+        state.destroy();
+    });
+    it("keeps the editor open when validation fails", async () => {
+        let value = "Original";
+        const onCommit = vi.fn(async () => undefined);
+        const state = new InlineEditState({
+            id: "title",
+            getLabel: () => "Title",
+            getValue: () => value,
+            setValue: (nextValue) => {
+                value = nextValue;
+            },
+            onCommit,
+            validate: (nextValue) => (nextValue ? null : "Title is required"),
+        });
+        await state.begin();
+        state.draft = "";
+        await state.commit();
+        expect(state.error).toBe("Title is required");
+        expect(state.editing).toBe(true);
+        expect(onCommit).not.toHaveBeenCalled();
+    });
+    it("ignores duplicate commits while persistence is pending", async () => {
+        let value = "Original";
+        let resolveCommit = () => undefined;
+        const pendingCommit = new Promise((resolve) => {
+            resolveCommit = resolve;
+        });
+        const onCommit = vi.fn(() => pendingCommit);
+        const state = new InlineEditState({
+            id: "title",
+            getLabel: () => "Title",
+            getValue: () => value,
+            setValue: (nextValue) => {
+                value = nextValue;
+            },
+            onCommit,
+        });
+        await state.begin();
+        state.draft = "Updated";
+        const firstCommit = state.commit();
+        await state.commit();
+        expect(onCommit).toHaveBeenCalledOnce();
+        resolveCommit("Updated");
+        await firstCommit;
+        state.destroy();
+    });
+    it("clears saved feedback after the configured duration", async () => {
+        vi.useFakeTimers();
+        let value = "Original";
+        const state = new InlineEditState({
+            id: "title",
+            getLabel: () => "Title",
+            getValue: () => value,
+            setValue: (nextValue) => {
+                value = nextValue;
+            },
+            onCommit: async (nextValue) => nextValue,
+            getSuccessDuration: () => 1500,
+        });
+        await state.begin();
+        state.draft = "Updated";
+        await state.commit();
+        expect(state.status).toBe("saved");
+        await vi.advanceTimersByTimeAsync(1500);
+        expect(state.status).toBe("idle");
+    });
+});

package/dist/lib/components/extended/inline-edit/inline-edit-status.svelte

@@ -0,0 +1,64 @@
+<script lang="ts">
+  import { cn, type WithElementRef } from "../../utils.js";
+
+  import { useInlineEditContext } from "./inline-edit.context.svelte.js";
+
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+
+  type InlineEditContext = ReturnType<typeof useInlineEditContext>;
+
+  type Props = WithElementRef<
+    Omit<HTMLAttributes<HTMLSpanElement>, "children">,
+    HTMLSpanElement
+  > & {
+    idle?: Snippet<[InlineEditContext]>;
+    saving?: Snippet<[InlineEditContext]>;
+    saved?: Snippet<[InlineEditContext]>;
+    savingLabel?: string;
+    savedLabel?: string;
+  };
+
+  let {
+    ref = $bindable(null),
+    idle,
+    saving,
+    saved,
+    savingLabel = "Saving",
+    savedLabel = "Saved",
+    class: className,
+    "data-slot": dataSlot = "inline-edit-status",
+    ...restProps
+  }: Props = $props();
+
+  const state = useInlineEditContext();
+
+  /** Exposes the status wrapper through the optional bindable ref. */
+  function attachRef(node: HTMLSpanElement): () => void {
+    ref = node;
+
+    return () => {
+      if (ref === node) {
+        ref = null;
+      }
+    };
+  }
+</script>
+
+<span
+  {@attach attachRef}
+  data-slot={dataSlot}
+  data-status={state.status}
+  class={cn("contents", className)}
+  {...restProps}
+>
+  {#if state.status === "saving"}
+    {@render saving?.(state)}
+    <span class="sr-only" role="status" aria-live="polite">{savingLabel}</span>
+  {:else if state.status === "saved"}
+    {@render saved?.(state)}
+    <span class="sr-only" role="status" aria-live="polite">{savedLabel}</span>
+  {:else}
+    {@render idle?.(state)}
+  {/if}
+</span>

package/dist/lib/components/extended/inline-edit/inline-edit-status.svelte.d.ts

@@ -0,0 +1,15 @@
+import { type WithElementRef } from "../../utils.js";
+import { useInlineEditContext } from "./inline-edit.context.svelte.js";
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+type InlineEditContext = ReturnType<typeof useInlineEditContext>;
+type Props = WithElementRef<Omit<HTMLAttributes<HTMLSpanElement>, "children">, HTMLSpanElement> & {
+    idle?: Snippet<[InlineEditContext]>;
+    saving?: Snippet<[InlineEditContext]>;
+    saved?: Snippet<[InlineEditContext]>;
+    savingLabel?: string;
+    savedLabel?: string;
+};
+declare const InlineEditStatus: import("svelte").Component<Props, {}, "ref">;
+type InlineEditStatus = ReturnType<typeof InlineEditStatus>;
+export default InlineEditStatus;

package/dist/lib/components/extended/inline-edit/inline-edit.context.svelte.d.ts

@@ -0,0 +1,5 @@
+import type { InlineEditState } from "./inline-edit-state.class.svelte.js";
+/** Registers inline-edit state for the current compound component tree. */
+export declare function setInlineEditContext(state: InlineEditState): InlineEditState;
+/** Returns the inline-edit state owned by the nearest root component. */
+export declare function useInlineEditContext(): InlineEditState;

package/dist/lib/components/extended/inline-edit/inline-edit.context.svelte.js

@@ -0,0 +1,14 @@
+import { getContext, setContext } from "svelte";
+const INLINE_EDIT_CONTEXT = Symbol.for("scn-inline-edit");
+/** Registers inline-edit state for the current compound component tree. */
+export function setInlineEditContext(state) {
+    return setContext(INLINE_EDIT_CONTEXT, state);
+}
+/** Returns the inline-edit state owned by the nearest root component. */
+export function useInlineEditContext() {
+    const state = getContext(INLINE_EDIT_CONTEXT);
+    if (!state) {
+        throw new Error("InlineEdit components must be used inside InlineEdit.Root");
+    }
+    return state;
+}