@geoffcox/sterling-svelte 2.0.2 → 2.0.3

package/README.md

@@ -0,0 +1,18 @@
+# sterling-svelte
+
+A modern, accessible, and lightweight component library for Svelte.
+
+## Installation
+
+```
+npm install @geoffcox/sterling-svelte
+```
+
+## Documentation
+
+The project builds the documentation for the library as a SvelteKit application.
+See the published version of the [documentation](https://geoffcox.github.io/docs/sterling-svelte/).
+
+## Repository
+
+https://github.com/GeoffCox/sterling-svelte

package/dist/@types/clickOutside.d.ts

@@ -0,0 +1,15 @@
+import type { EventHandler } from 'svelte/elements';
+
+export type ClickOutsideEventDetail = {
+  mouseEvent: MouseEvent;
+};
+
+export type ClickOutsideEvent = CustomEvent<ClickOutsideEventDetail>;
+
+declare module 'svelte/elements' {
+  export interface DOMAttributes<T extends EventTarget> {
+    'on:click_outside'?: EventHandler<ClickOutsideEvent, T>;
+  }
+}
+
+export {}; // ensure this is not an ambient module, else types will be overridden instead of augmented

package/dist/Button.svelte

@@ -0,0 +1,29 @@
+<svelte:options runes={true} />
+
+<script lang="ts">
+  import type { HTMLButtonAttributes } from 'svelte/elements';
+
+  type Props = HTMLButtonAttributes;
+
+  let { children, class: _class, ...rest }: Props = $props();
+
+  let buttonRef: HTMLButtonElement;
+
+  export const click = () => {
+    buttonRef?.click();
+  };
+
+  export const blur = () => {
+    buttonRef?.blur();
+  };
+
+  export const focus = (options?: FocusOptions) => {
+    buttonRef?.focus(options);
+  };
+</script>
+
+<button bind:this={buttonRef} class={['sterling-button', _class]} type="button" {...rest}>
+  {#if children}
+    {@render children()}
+  {/if}
+</button>

package/dist/Button.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { HTMLButtonAttributes } from 'svelte/elements';
+declare const Button: import("svelte").Component<HTMLButtonAttributes, {
+    click: () => void;
+    blur: () => void;
+    focus: (options?: FocusOptions) => void;
+}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/Callout.svelte

@@ -0,0 +1,243 @@
+<svelte:options runes={true} />
+
+<script lang="ts">
+  import {
+    arrow,
+    autoUpdate,
+    computePosition,
+    flip,
+    offset,
+    type ComputePositionReturn,
+    type Placement
+  } from '@floating-ui/dom';
+  import { getContext, tick } from 'svelte';
+  import type { HTMLAttributes, KeyboardEventHandler } from 'svelte/elements';
+  import { fade, type FadeParams, type TransitionConfig } from 'svelte/transition';
+  import { portal } from './actions/portal';
+  import { prefersReducedMotion } from './mediaQueries/prefersReducedMotion';
+  import type { PopoverPlacement } from './Popover.types';
+  import { STERLING_PORTAL_CONTEXT_ID, STERLING_PORTAL_HOST_ID } from './Portal.constants';
+  import type { PortalContext } from './Portal.types';
+
+  type Props = HTMLAttributes<HTMLDivElement> & {
+    conditionalRender?: boolean | null;
+    crossAxisOffset?: number;
+    mainAxisOffset?: number;
+    open?: boolean | null;
+    placement?: PopoverPlacement;
+    portalHost?: HTMLElement;
+    reference?: HTMLElement | null;
+  };
+
+  let {
+    children,
+    conditionalRender = $bindable(true),
+    crossAxisOffset = $bindable(0),
+    mainAxisOffset = $bindable(0),
+    open = $bindable(false),
+    placement = $bindable('top-start'),
+    portalHost,
+    reference,
+    class: _class,
+    ...rest
+  }: Props = $props();
+
+  let popupRef: HTMLDivElement | undefined = $state(undefined);
+  let arrowRef: HTMLDivElement | undefined = $state(undefined);
+  let popupPosition: Partial<ComputePositionReturn> = $state({ x: 0, y: 0 });
+  let floatingUIPlacement = $derived(placement as Placement);
+  let bodyHeight = $state(0);
+  let resizeObserver: ResizeObserver | undefined = undefined;
+
+  const portalContext = getContext<PortalContext>(STERLING_PORTAL_CONTEXT_ID) || {
+    portalHost: undefined
+  };
+
+  const ensurePortalHost = async () => {
+    await tick();
+
+    // use the host set from context, usually set from a Dialog
+    let host = portalContext.portalHost;
+
+    // use or create the sterling portal host
+    if (!host && globalThis?.document) {
+      host = globalThis.document.querySelector(`#${STERLING_PORTAL_HOST_ID}`) as HTMLElement;
+
+      // fallback to creating the sterling portal host
+      if (!host) {
+        host = globalThis.document.createElement('div');
+        host.id = STERLING_PORTAL_HOST_ID;
+        host.style.overflow = 'visible';
+        globalThis.document.body.append(host);
+      }
+    }
+
+    portalHost = host;
+  };
+
+  let middleware = $derived([
+    offset({ mainAxis: mainAxisOffset, crossAxis: crossAxisOffset }),
+    flip(),
+    arrowRef && arrow({ element: arrowRef, padding: 8 })
+  ]);
+
+  const computeCalloutPosition = async () => {
+    if (reference && popupRef) {
+      popupPosition = await computePosition(reference, popupRef, {
+        placement: floatingUIPlacement,
+        middleware
+      });
+    } else {
+      popupPosition = { x: 0, y: 0 };
+    }
+  };
+
+  // whenever a positioned element is portaled it needs resubscription to auto-update
+  let cleanupAutoUpdate = () => {};
+
+  const autoUpdateCalloutPosition = () => {
+    cleanupAutoUpdate();
+    cleanupAutoUpdate = () => {};
+    if (reference && popupRef) {
+      cleanupAutoUpdate = autoUpdate(reference, popupRef, computeCalloutPosition);
+    }
+  };
+
+  $effect(() => {
+    autoUpdateCalloutPosition();
+    return () => {
+      cleanupAutoUpdate();
+      cleanupAutoUpdate = () => {};
+    };
+  });
+
+  $effect(() => {
+    bodyHeight;
+    reference;
+    computeCalloutPosition();
+  });
+
+  // ----- Arrow ----- //
+
+  const getArrowPlacementStyle = (position?: Partial<ComputePositionReturn>) => {
+    if (position?.placement && arrowRef) {
+      switch (position.placement) {
+        case 'top':
+        case 'top-start':
+        case 'top-end':
+          return (
+            `bottom: -${arrowRef.offsetWidth}px;` + `transform:translate(0, -50%) rotate(135deg);`
+          );
+        case 'right':
+        case 'right-start':
+        case 'right-end':
+          return (
+            `left: -${arrowRef.offsetWidth}px;` + `transform:translate(50%, 0) rotate(225deg);`
+          );
+        case 'bottom':
+        case 'bottom-start':
+        case 'bottom-end':
+          return `top: -${arrowRef.offsetWidth}px;` + `transform:translate(0, 50%) rotate(-45deg);`;
+        case 'left':
+        case 'left-start':
+        case 'left-end':
+          return (
+            `right: -${arrowRef.offsetWidth}px;` + `transform:translate(-50%, 0) rotate(45deg);`
+          );
+      }
+    }
+    return '';
+  };
+
+  const getArrowOffsetStyle = (position?: Partial<ComputePositionReturn>) => {
+    const arrow = position?.middlewareData?.arrow;
+    if (arrow) {
+      if (arrow.x !== null && arrow.x !== undefined) {
+        return `left: ${arrow.x}px;`;
+      } else if (arrow.y !== null && arrow.y !== undefined) {
+        return `top: ${arrow.y}px;`;
+      }
+    }
+    return '';
+  };
+
+  let arrowStyle = $derived(
+    getArrowPlacementStyle(popupPosition) + getArrowOffsetStyle(popupPosition)
+  );
+
+  // ----- Animation ----- //
+
+  const fadeNoOp = (node: Element, params?: FadeParams): TransitionConfig => {
+    return { delay: 0, duration: 0 };
+  };
+
+  let fadeMotion = $derived(!$prefersReducedMotion ? fade : fadeNoOp);
+
+  // ----- EventHandlers ----- //
+
+  const onKeydown: KeyboardEventHandler<HTMLDivElement> = (event) => {
+    if (event.key === 'Escape') {
+      open = false;
+    }
+    rest.onkeydown?.(event);
+  };
+
+  $effect(() => {
+    ensurePortalHost();
+
+    resizeObserver = new ResizeObserver((entries) => {
+      bodyHeight = entries[0].target.clientHeight;
+    });
+
+    // start observing a DOM node
+    resizeObserver.observe(document.body);
+
+    return () => {
+      resizeObserver?.unobserve(document.body);
+      resizeObserver?.disconnect();
+      resizeObserver = undefined;
+    };
+  });
+
+  ensurePortalHost();
+</script>
+
+{#if open || !conditionalRender}
+  <div
+    use:portal={{ target: portalHost }}
+    class="sterling-callout-portal"
+    transition:fadeMotion|global={{ duration: 250 }}
+  >
+    <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+    <div
+      bind:this={popupRef}
+      class={['sterling-callout', _class]}
+      class:open
+      class:top={popupPosition.placement === 'top'}
+      class:top-start={popupPosition.placement === 'top-start'}
+      class:top-end={popupPosition.placement === 'top-end'}
+      class:right={popupPosition.placement === 'right'}
+      class:right-start={popupPosition.placement === 'right-start'}
+      class:right-end={popupPosition.placement === 'right-end'}
+      class:bottom={popupPosition.placement === 'bottom'}
+      class:bottom-start={popupPosition.placement === 'bottom-start'}
+      class:bottom-end={popupPosition.placement === 'bottom-end'}
+      class:left={popupPosition.placement === 'left'}
+      class:left-start={popupPosition.placement === 'left-start'}
+      class:left-end={popupPosition.placement === 'left-end'}
+      role="tooltip"
+      {...rest}
+      onkeydown={onKeydown}
+      style="left:{popupPosition.x}px; top:{popupPosition.y}px"
+    >
+      {#if children}
+        {#if typeof children === 'string'}
+          <div class="callout-text">{children}</div>
+        {:else}
+          {@render children()}
+        {/if}
+      {/if}
+      <div class="arrow" bind:this={arrowRef} style={arrowStyle}></div>
+    </div>
+  </div>
+{/if}

package/dist/Callout.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { PopoverPlacement } from './Popover.types';
+type Props = HTMLAttributes<HTMLDivElement> & {
+    conditionalRender?: boolean | null;
+    crossAxisOffset?: number;
+    mainAxisOffset?: number;
+    open?: boolean | null;
+    placement?: PopoverPlacement;
+    portalHost?: HTMLElement;
+    reference?: HTMLElement | null;
+};
+declare const Callout: import("svelte").Component<Props, {}, "conditionalRender" | "crossAxisOffset" | "mainAxisOffset" | "open" | "placement">;
+type Callout = ReturnType<typeof Callout>;
+export default Callout;

package/dist/Callout.types.d.ts

@@ -0,0 +1,11 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import type { PopoverPlacement } from './Popover.types';
+export type CalloutProps = HTMLAttributes<HTMLDivElement> & {
+    conditionalRender?: boolean | null;
+    crossAxisOffset?: number;
+    mainAxisOffset?: number;
+    open?: boolean | null;
+    placement?: PopoverPlacement;
+    portalHost?: HTMLElement;
+    reference?: HTMLElement | null;
+};

package/dist/Callout.types.js

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

package/dist/Checkbox.svelte

@@ -0,0 +1,62 @@
+<svelte:options runes={true} />
+
+<script lang="ts">
+  import type { HTMLInputAttributes } from 'svelte/elements';
+  import { usingKeyboard } from './mediaQueries/usingKeyboard';
+
+  const uuid = $props.id();
+
+  type Props = HTMLInputAttributes;
+
+  let {
+    id,
+    children,
+    checked = $bindable(false),
+    class: _class,
+    disabled = $bindable(false),
+    ...rest
+  }: Props = $props();
+
+  let inputRef: HTMLInputElement;
+
+  $effect(() => {
+    if (children && id === undefined) {
+      id = `Checkbox-${uuid}`;
+    }
+  });
+
+  // ----- Methods ----- //
+
+  export const blur = () => {
+    inputRef?.blur();
+  };
+
+  export const click = () => {
+    inputRef?.click();
+  };
+
+  export const focus = (options?: FocusOptions) => {
+    inputRef?.focus(options);
+  };
+</script>
+
+<!--
+	@component
+	A styled HTML input type=checkbox element.
+-->
+<div
+  class={['sterling-checkbox', _class]}
+  class:checked
+  class:disabled
+  class:using-keyboard={$usingKeyboard}
+>
+  <div class="container">
+    <input bind:this={inputRef} bind:checked {disabled} {id} type="checkbox" {...rest} />
+    <div class="indicator"></div>
+  </div>
+  {#if children}
+    <label for={id}>
+      {@render children()}
+    </label>
+  {/if}
+</div>

package/dist/Checkbox.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+/** A styled HTML input type=checkbox element. */
+declare const Checkbox: import("svelte").Component<HTMLInputAttributes, {
+    blur: () => void;
+    click: () => void;
+    focus: (options?: FocusOptions) => void;
+}, "disabled" | "checked">;
+type Checkbox = ReturnType<typeof Checkbox>;
+export default Checkbox;

package/dist/Dialog.svelte

@@ -0,0 +1,201 @@
+<svelte:options runes={true} />
+
+<script lang="ts">
+  import { onMount, setContext, tick, type Snippet } from 'svelte';
+  import type { FormEventHandler, HTMLDialogAttributes } from 'svelte/elements';
+  import { writable } from 'svelte/store';
+  import Button from './Button.svelte';
+  import { STERLING_PORTAL_CONTEXT_ID } from './Portal.constants';
+  import type { PortalContext } from './Portal.types';
+
+  const dialogFadeDuration = 250;
+
+  type Props = HTMLDialogAttributes & {
+    backdropCloses?: boolean | null | undefined;
+    body?: Snippet;
+    content?: Snippet;
+    footer?: Snippet;
+    header?: Snippet;
+    returnValue?: string;
+    headerTitle?: string | Snippet;
+  };
+
+  let {
+    backdropCloses = false,
+    open = $bindable(false),
+    body,
+    class: _class,
+    content,
+    footer,
+    header,
+    returnValue = $bindable(''),
+    headerTitle,
+    ...rest
+  }: Props = $props();
+
+  let dialogRef: HTMLDialogElement;
+  let contentRef: HTMLDivElement;
+  let formRef: HTMLFormElement;
+
+  // svelte-ignore non_reactive_update
+  let closing = false;
+
+  let portalHost: HTMLElement | undefined = $state(undefined);
+
+  let portalContext: PortalContext = {
+    get portalHost() {
+      return portalHost;
+    },
+    set portalHost(host: HTMLElement | undefined) {
+      portalHost = host;
+    }
+  };
+
+  // ----- Context ----- //
+  setContext<PortalContext>(STERLING_PORTAL_CONTEXT_ID, portalContext);
+
+  // ----- Event Handlers ----- //
+
+  const onDocumentClick = (event: MouseEvent) => {
+    // as tracking clicks outside the dialog is only active while the dialog is open
+    // the clickOutside action is not used and reimplemented here.
+    const targetNode = event?.target as Node;
+    // the content must be used as the container because dialog::backdrop is considered
+    // part of the HTMLDialogElement
+    if (targetNode && !contentRef?.contains(targetNode) && backdropCloses) {
+      open = false;
+    }
+  };
+
+  const showDialog = () => {
+    if (dialogRef?.open === false) {
+      // when open, track clicks outside the dialog (use capture = true)
+      document.addEventListener('click', onDocumentClick, true);
+      returnValue = '';
+      dialogRef.showModal();
+    }
+    open = true;
+  };
+
+  const closeDialog = async () => {
+    if (dialogRef?.open === true) {
+      // when closed, stop tracking clicks outside the dialog
+      document.removeEventListener('click', onDocumentClick);
+
+      // to allow time for the CSS transition animation, closing the dialog is delayed
+      closing = true;
+      await tick();
+      setTimeout(() => {
+        dialogRef.close(returnValue);
+        open = false;
+        closing = false;
+      }, dialogFadeDuration);
+    } else {
+      open = false;
+    }
+  };
+
+  const updateDialog = (open: boolean | null | undefined) => {
+    if (open) {
+      showDialog();
+    } else {
+      closeDialog();
+    }
+  };
+
+  const onCancel = (event: Event) => {
+    // Cancelling a dialog instantly hides the dialog.
+    // To allow animation with closeDialog, this event is canceled.
+    event.preventDefault();
+    event.stopPropagation();
+    returnValue = '';
+    closeDialog();
+    return false;
+  };
+
+  const onSubmit: FormEventHandler<HTMLFormElement> = (event) => {
+    // Submitting a form instantly hides the dialog.
+    // The dialog.close event is not cancellable, but form.submit is.
+    // To allow animation with closeDialog, this event is canceled.
+    // The form is resubmitted after the dialog closes to ensure the form is in the correct state.
+    const anyEvent = event as unknown as any;
+    if (anyEvent?.submitter.type === 'submit') {
+      if (dialogRef.open) {
+        const eventSubmitter = anyEvent?.submitter;
+        returnValue = eventSubmitter?.value ?? '';
+        closeDialog();
+        setTimeout(() => {
+          formRef.requestSubmit(eventSubmitter);
+        }, dialogFadeDuration);
+        event.preventDefault();
+        return false;
+      }
+    } else {
+      event.preventDefault();
+      return false;
+    }
+  };
+
+  $effect(() => {
+    updateDialog(open);
+  });
+
+  onMount(() => {
+    updateDialog(open);
+
+    // Use the dialog for any element portals
+    portalContext.portalHost = dialogRef;
+
+    dialogRef.addEventListener('cancel', onCancel);
+
+    return () => {
+      dialogRef?.removeEventListener('cancel', onCancel);
+
+      portalContext.portalHost = undefined;
+    };
+  });
+</script>
+
+<dialog
+  bind:this={dialogRef}
+  class={['sterling-dialog', _class]}
+  class:open
+  class:closing
+  {...rest}
+>
+  <form method="dialog" bind:this={formRef} onsubmit={onSubmit}>
+    <div class="content" bind:this={contentRef}>
+      {#if content}
+        {@render content()}
+      {:else}
+        <div class="header">
+          {#if header}
+            {@render header()}
+          {:else}
+            <div class="title">
+              {#if headerTitle}
+                {#if typeof headerTitle === 'string'}
+                  {headerTitle}
+                {:else}
+                  {@render headerTitle()}
+                {/if}
+              {/if}
+            </div>
+            <div class="close">
+              <Button class="circular tool" onclick={() => closeDialog()}>
+                <div class="close-x"></div>
+              </Button>
+            </div>
+          {/if}
+        </div>
+        <div class="body">
+          {@render body?.()}
+        </div>
+        <div class="separator"></div>
+        <div class="footer">
+          {@render footer?.()}
+        </div>
+      {/if}
+    </div>
+  </form>
+</dialog>

package/dist/Dialog.svelte.d.ts

@@ -0,0 +1,14 @@
+import { type Snippet } from 'svelte';
+import type { HTMLDialogAttributes } from 'svelte/elements';
+type Props = HTMLDialogAttributes & {
+    backdropCloses?: boolean | null | undefined;
+    body?: Snippet;
+    content?: Snippet;
+    footer?: Snippet;
+    header?: Snippet;
+    returnValue?: string;
+    headerTitle?: string | Snippet;
+};
+declare const Dialog: import("svelte").Component<Props, {}, "open" | "returnValue">;
+type Dialog = ReturnType<typeof Dialog>;
+export default Dialog;