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

package/src/lib/components/extended/inline-edit/inline-edit-display.svelte

@@ -0,0 +1,74 @@
+<script lang="ts">
+  import { cn, type WithElementRef } from "$lib/components/utils.js";
+
+  import { useInlineEditContext } from "./inline-edit.context.svelte.js";
+
+  import type { Snippet } from "svelte";
+  import type { HTMLButtonAttributes } from "svelte/elements";
+
+  type Props = WithElementRef<
+    Omit<HTMLButtonAttributes, "children">,
+    HTMLButtonElement
+  > & {
+    children?: Snippet<[ReturnType<typeof useInlineEditContext>]>;
+  };
+
+  let {
+    ref = $bindable(null),
+    children,
+    class: className,
+    type = "button",
+    onclick,
+    "aria-label": ariaLabel,
+    "data-slot": dataSlot = "inline-edit-display",
+    ...restProps
+  }: Props = $props();
+
+  const state = useInlineEditContext();
+
+  /** Opens the editor after allowing consumers to intercept the display click. */
+  function handleClick(
+    event: MouseEvent & { currentTarget: EventTarget & HTMLButtonElement },
+  ): void {
+    onclick?.(event);
+
+    if (event.defaultPrevented) {
+      return;
+    }
+
+    void state.begin();
+  }
+
+  /** Exposes the display button through the optional bindable ref. */
+  function attachRef(node: HTMLButtonElement): () => void {
+    ref = node;
+
+    return () => {
+      if (ref === node) {
+        ref = null;
+      }
+    };
+  }
+</script>
+
+{#if !state.editing}
+  <button
+    {@attach attachRef}
+    {type}
+    data-slot={dataSlot}
+    data-status={state.status}
+    class={cn(
+      "focus-visible:ring-ring/50 hover:bg-muted/40 inline-flex min-w-0 items-center justify-start gap-2 rounded-md text-left outline-none focus-visible:ring-[3px]",
+      className,
+    )}
+    aria-label={ariaLabel ?? `Edit ${state.label}`}
+    onclick={handleClick}
+    {...restProps}
+  >
+    {#if children}
+      {@render children(state)}
+    {:else}
+      <span class="min-w-0 truncate">{state.value}</span>
+    {/if}
+  </button>
+{/if}

package/src/lib/components/extended/inline-edit/inline-edit-error.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+  import { cn, type WithElementRef } from "$lib/components/utils.js";
+
+  import { useInlineEditContext } from "./inline-edit.context.svelte.js";
+
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+
+  type Props = WithElementRef<
+    Omit<HTMLAttributes<HTMLSpanElement>, "children">,
+    HTMLSpanElement
+  > & {
+    children?: Snippet<[ReturnType<typeof useInlineEditContext>]>;
+  };
+
+  let {
+    ref = $bindable(null),
+    children,
+    class: className,
+    "data-slot": dataSlot = "inline-edit-error",
+    ...restProps
+  }: Props = $props();
+
+  const state = useInlineEditContext();
+
+  /** Exposes the rendered error through the optional bindable ref. */
+  function attachRef(node: HTMLSpanElement): () => void {
+    ref = node;
+
+    return () => {
+      if (ref === node) {
+        ref = null;
+      }
+    };
+  }
+</script>
+
+{#if state.error}
+  <span
+    {@attach attachRef}
+    id={state.errorId}
+    data-slot={dataSlot}
+    class={cn("text-destructive text-sm font-normal", className)}
+    role="alert"
+    {...restProps}
+  >
+    {#if children}
+      {@render children(state)}
+    {:else}
+      {state.error}
+    {/if}
+  </span>
+{/if}

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

@@ -0,0 +1,125 @@
+<script lang="ts">
+  import Input from "$lib/components/ui/input/input.svelte";
+  import { cn, type WithElementRef } from "$lib/components/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/src/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 "$lib/components/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/src/lib/components/extended/inline-edit/inline-edit-state.class.svelte.test.ts

@@ -0,0 +1,133 @@
+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: string) => 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: (value: string) => void = () => undefined;
+    const pendingCommit = new Promise<string>((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/src/lib/components/extended/inline-edit/inline-edit-state.class.svelte.ts

@@ -0,0 +1,212 @@
+import { tick } from "svelte";
+
+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;
+};
+
+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 {
+  readonly errorId: string;
+  readonly inputId: string;
+
+  draft = $state("");
+  editing = $state(false);
+  error = $state<string | null>(null);
+  status = $state<InlineEditStatus>("idle");
+  saving = $derived(this.status === "saving");
+  saved = $derived(this.status === "saved");
+
+  #input = $state<HTMLInputElement | null>(null);
+  readonly #options: InlineEditStateOptions;
+  #savedTimeout: ReturnType<typeof setTimeout> | null = null;
+
+  /** Creates state backed by getter and setter callbacks from the root component. */
+  constructor(options: InlineEditStateOptions) {
+    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(): string {
+    return this.#options.getLabel();
+  }
+
+  /** Returns the current committed value supplied by the root component. */
+  get value(): string {
+    return this.#options.getValue();
+  }
+
+  /** Opens the editor and focuses its input with the committed value selected. */
+  begin = async (): Promise<void> => {
+    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 = (): void => {
+    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: string): void => {
+    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?: string): Promise<void> => {
+    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: KeyboardEvent): void => {
+    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: HTMLInputElement): (() => void) => {
+    this.#input = input;
+
+    return () => {
+      if (this.#input === input) {
+        this.#input = null;
+      }
+    };
+  };
+
+  /** Cancels pending saved-feedback work when the root component is destroyed. */
+  destroy = (): void => {
+    if (this.#savedTimeout === null) {
+      return;
+    }
+
+    clearTimeout(this.#savedTimeout);
+    this.#savedTimeout = null;
+  };
+
+  /** Focuses and selects the input after Svelte has rendered it. */
+  async #focus(): Promise<void> {
+    await tick();
+    this.#input?.focus();
+    this.#input?.select();
+  }
+
+  /** Clears saved feedback without interrupting an in-flight save. */
+  #clearSaved(): void {
+    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(): void {
+    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: unknown): string {
+    if (error instanceof Error) {
+      return error.message;
+    }
+
+    return this.#options.getErrorMessage?.() ?? DEFAULT_ERROR_MESSAGE;
+  }
+}