components-svelte 0.1.0

package/dist/components/property/Property.svelte

@@ -0,0 +1,123 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import { MAX_DEFAULT_VALUE_LENGTH } from "../../constants";
+  import { Classes } from "../../constants/selectors";
+  import { cn } from "../../utils/cn";
+  import ParamHead from "./ParamHead.svelte";
+
+  type PropertyProps = {
+    name: string;
+    type: string;
+    location?: string;
+    hidden?: boolean;
+    default?: unknown;
+    required?: boolean;
+    deprecated?: boolean;
+    children?: Snippet | string;
+    id?: string;
+    pre?: string[];
+    post?: string[];
+    class?: string;
+    className?: string;
+    onMount?: () => void;
+    navigateToHeaderAriaLabel?: string;
+    defaultLabel?: string;
+    requiredLabel?: string;
+    deprecatedLabel?: string;
+  };
+
+  const DEFAULT_NAVIGATE_TO_HEADER_ARIA_LABEL = "Navigate to header";
+  const DEFAULT_DEFAULT_LABEL = "default";
+  const DEFAULT_REQUIRED_LABEL = "required";
+  const DEFAULT_DEPRECATED_LABEL = "deprecated";
+
+  let {
+    name,
+    type,
+    location,
+    hidden,
+    default: defaultValue,
+    required,
+    deprecated,
+    children,
+    id,
+    pre,
+    post,
+    class: classAttribute,
+    className,
+    onMount,
+    navigateToHeaderAriaLabel = DEFAULT_NAVIGATE_TO_HEADER_ARIA_LABEL,
+    defaultLabel = DEFAULT_DEFAULT_LABEL,
+    requiredLabel = DEFAULT_REQUIRED_LABEL,
+    deprecatedLabel = DEFAULT_DEPRECATED_LABEL,
+  }: PropertyProps = $props();
+
+  let propertyClass = $derived(
+    cn(
+      Classes.Field,
+      "my-2.5 border-stone-50 border-b pt-2.5 pb-5 dark:border-stone-800/50",
+      classAttribute ?? className
+    )
+  );
+
+  let stringifiedDefaultValue = $derived.by(() => {
+    if (defaultValue !== null && typeof defaultValue === "object") {
+      // don't display values with nested objects; looks bad on one line
+      const containsNestedObject = Object.values(
+        defaultValue as Record<string, unknown>
+      ).some((value) => value !== null && typeof value === "object");
+
+      if (containsNestedObject) {
+        return null;
+      }
+    }
+
+    try {
+      const stringifiedValue = JSON.stringify(defaultValue);
+      if (
+        stringifiedValue &&
+        stringifiedValue.length > 0 &&
+        stringifiedValue.length < MAX_DEFAULT_VALUE_LENGTH
+      ) {
+        return stringifiedValue;
+      }
+    } catch {
+      return null;
+    }
+
+    return null;
+  });
+</script>
+
+{#if !hidden}
+  <div class={propertyClass}>
+    <ParamHead
+      default={stringifiedDefaultValue}
+      defaultLabel={defaultLabel}
+      deprecated={deprecated}
+      deprecatedLabel={deprecatedLabel}
+      id={id}
+      location={location}
+      name={name}
+      navigateToHeaderAriaLabel={navigateToHeaderAriaLabel}
+      onMount={onMount}
+      post={post}
+      pre={pre}
+      required={required}
+      requiredLabel={requiredLabel}
+      type={type}
+    />
+    {#if children}
+      <div
+        class="prose-sm prose-stone dark:prose-invert mt-4 [&_.prose>p:first-child]:mt-0 [&_.prose>p:last-child]:mb-0"
+        data-component-part="field-content"
+      >
+        {#if typeof children === "string"}
+          {children}
+        {:else}
+          {@render children()}
+        {/if}
+      </div>
+    {/if}
+  </div>
+{/if}

package/dist/components/property/Property.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { Snippet } from "svelte";
+type PropertyProps = {
+    name: string;
+    type: string;
+    location?: string;
+    hidden?: boolean;
+    default?: unknown;
+    required?: boolean;
+    deprecated?: boolean;
+    children?: Snippet | string;
+    id?: string;
+    pre?: string[];
+    post?: string[];
+    class?: string;
+    className?: string;
+    onMount?: () => void;
+    navigateToHeaderAriaLabel?: string;
+    defaultLabel?: string;
+    requiredLabel?: string;
+    deprecatedLabel?: string;
+};
+declare const Property: import("svelte").Component<PropertyProps, {}, "">;
+type Property = ReturnType<typeof Property>;
+export default Property;

package/dist/components/property/RequiredPill.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  type RequiredPillProps = {
+    label?: string;
+  };
+
+  let { label }: RequiredPillProps = $props();
+</script>
+
+{#if label}
+  <div
+    class="whitespace-nowrap rounded-md bg-red-100/50 px-2 py-0.5 font-medium text-red-600 dark:bg-red-400/10 dark:text-red-300"
+    data-component-part="field-required-pill"
+  >
+    {label}
+  </div>
+{/if}

package/dist/components/property/RequiredPill.svelte.d.ts

@@ -0,0 +1,6 @@
+type RequiredPillProps = {
+    label?: string;
+};
+declare const RequiredPill: import("svelte").Component<RequiredPillProps, {}, "">;
+type RequiredPill = ReturnType<typeof RequiredPill>;
+export default RequiredPill;

package/dist/components/property/index.d.ts

@@ -0,0 +1,11 @@
+import DeprecatedPill from "./DeprecatedPill.svelte";
+import InfoPill from "./InfoPill.svelte";
+import ParamHead from "./ParamHead.svelte";
+import Property from "./Property.svelte";
+import RequiredPill from "./RequiredPill.svelte";
+export type { default as ParamHeadProps } from "./ParamHead.svelte";
+export type { default as DeprecatedPillProps } from "./DeprecatedPill.svelte";
+export type { default as InfoPillProps } from "./InfoPill.svelte";
+export type { default as PropertyProps } from "./Property.svelte";
+export type { default as RequiredPillProps } from "./RequiredPill.svelte";
+export { DeprecatedPill, InfoPill, ParamHead, Property, RequiredPill };

package/dist/components/property/index.js

@@ -0,0 +1,6 @@
+import DeprecatedPill from "./DeprecatedPill.svelte";
+import InfoPill from "./InfoPill.svelte";
+import ParamHead from "./ParamHead.svelte";
+import Property from "./Property.svelte";
+import RequiredPill from "./RequiredPill.svelte";
+export { DeprecatedPill, InfoPill, ParamHead, Property, RequiredPill };

package/dist/components/search/index.d.ts

@@ -0,0 +1,7 @@
+export type { SearchButtonProps } from "../SearchButton.svelte";
+export { default as SearchButton } from "../SearchButton.svelte";
+export type { SearchContextValue, SearchProviderProps } from "../SearchProvider.svelte";
+export { default as SearchProvider } from "../SearchProvider.svelte";
+export { useSearch } from "./use-search";
+export type { SearchProps, SearchResult } from "../Search.svelte";
+export { default as Search } from "../Search.svelte";

package/dist/components/search/index.js

@@ -0,0 +1,4 @@
+export { default as SearchButton } from "../SearchButton.svelte";
+export { default as SearchProvider } from "../SearchProvider.svelte";
+export { useSearch } from "./use-search";
+export { default as Search } from "../Search.svelte";

package/dist/components/search/use-search.d.ts

@@ -0,0 +1,9 @@
+type SearchContextValue = {
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+};
+declare const useSearch: () => SearchContextValue | null;
+export { useSearch };
+export type { SearchContextValue };

package/dist/components/search/use-search.js

@@ -0,0 +1,6 @@
+import { getContext } from "svelte";
+// Svelte equivalent of React's useSearch() context hook.
+const useSearch = () => {
+    return getContext("search-context");
+};
+export { useSearch };

package/dist/components/steps/Step.svelte

@@ -0,0 +1,314 @@
+<script lang="ts">
+  import { getContext, onMount, untrack } from "svelte";
+  import type { Snippet } from "svelte";
+  import Icon from "../icon/Icon.svelte";
+  import { Classes } from "../../constants/selectors";
+  import { copyToClipboard } from "../../utils/copy-to-clipboard";
+  import { cn } from "../../utils/cn";
+  import type { IconLibrary, IconType } from "../../utils/icon-utils";
+  import { STEPS_CONTEXT, type StepsContext } from "./context";
+  import { STEP_TITLE_SIZES, type StepTitleSize } from "./constants";
+
+  type Numberish = number | `${number}`;
+
+  type StepProps = {
+    icon?: string | Snippet;
+    stepNumber?: Numberish;
+    iconType?: IconType;
+    iconLibrary?: IconLibrary;
+    title: string | Snippet;
+    children?: string | Snippet;
+    titleSize?: StepTitleSize;
+    class?: string;
+    className?: string;
+    isLast?: boolean;
+    id?: string;
+    noAnchor?: boolean;
+    scrollElementIntoView?: (id: string) => void;
+    onCopyAnchorLink?: (id: string | undefined) => void;
+    onRegisterHeading?: (id: string, rect: DOMRect) => void;
+    onUnregisterHeading?: (id: string) => void;
+    _hasContext?: boolean;
+  };
+
+  let {
+    stepNumber,
+    icon,
+    iconType,
+    iconLibrary,
+    title,
+    children,
+    titleSize,
+    class: classAttribute,
+    className,
+    isLast = false,
+    id,
+    noAnchor = false,
+    scrollElementIntoView,
+    onRegisterHeading,
+    onUnregisterHeading,
+    _hasContext,
+    onCopyAnchorLink,
+  }: StepProps = $props();
+
+  const stepsContext = getContext<StepsContext | undefined>(STEPS_CONTEXT);
+  const stepId = Symbol("steps-item");
+
+  let stepElement: HTMLDivElement | null = $state(null);
+  let rect: DOMRect | null = $state(null);
+  let isTitleHovered = $state(false);
+
+  $effect(() => {
+    if (!stepsContext) {
+      return;
+    }
+
+    untrack(() => stepsContext.register(stepId));
+    return () => untrack(() => stepsContext.unregister(stepId));
+  });
+
+  function observeStep(node: HTMLDivElement) {
+    stepElement = node;
+
+    const measure = () => {
+      rect = node.getBoundingClientRect();
+    };
+
+    measure();
+
+    if (typeof ResizeObserver === "undefined") {
+      return;
+    }
+
+    const resizeObserver = new ResizeObserver(measure);
+    resizeObserver.observe(node);
+
+    return {
+      destroy() {
+        resizeObserver.unobserve(node);
+        if (stepElement === node) {
+          stepElement = null;
+        }
+      },
+    };
+  }
+
+  let stepIndex = $derived(stepsContext?.items.indexOf(stepId) ?? 0);
+  let stepCount = $derived(stepsContext?.items.length ?? 1);
+  let resolvedStepNumber = $derived(stepNumber ?? stepIndex + 1);
+  let resolvedTitleSize = $derived(titleSize ?? stepsContext?.titleSize ?? "p");
+  let titleTag = $derived(
+    STEP_TITLE_SIZES.includes(resolvedTitleSize) ? resolvedTitleSize : "p"
+  );
+  let isAnchorEnabled = $derived(titleTag === "h2" || titleTag === "h3");
+  let resolvedIsLast = $derived(
+    stepsContext ? stepIndex === stepCount - 1 : isLast
+  );
+  let itemClass = $derived(
+    cn(
+      Classes.Step,
+      "group/step relative flex items-start pb-5",
+      classAttribute ?? className
+    )
+  );
+
+  // Match React's heading registration effect for integrations that provide
+  // the optional heading context callbacks.
+  $effect(() => {
+    if (!(_hasContext && id && rect)) {
+      return;
+    }
+
+    onRegisterHeading?.(id, rect);
+
+    return () => {
+      onUnregisterHeading?.(id);
+    };
+  });
+
+  // Scrolling happens only once, on initial load, after the element mounts.
+  onMount(() => {
+    if (!id || noAnchor) {
+      return;
+    }
+
+    try {
+      const hash = decodeURIComponent(window.location.hash.substring(1));
+      if (hash === id) {
+        scrollElementIntoView?.(id);
+      }
+    } catch {
+      // silently fail if the hash is invalid
+    }
+  });
+
+  async function copyAnchorLink() {
+    if (!isAnchorEnabled || noAnchor || !id || typeof window === "undefined") {
+      return;
+    }
+
+    const encodedId = encodeURIComponent(id);
+    const result = await copyToClipboard(
+      `${window.location.href.split("#")[0]}#${encodedId}`
+    );
+
+    if (result === "success") {
+      window.location.hash = encodedId;
+      onCopyAnchorLink?.(id);
+    }
+  }
+
+  function toggleAnchor(shown: boolean) {
+    if (!isAnchorEnabled || noAnchor || !id) {
+      return;
+    }
+
+    isTitleHovered = shown;
+  }
+
+  const titleClasses = "mt-2 text-stone-900 dark:text-stone-200";
+</script>
+
+<!-- Svelte preserves the original list-item wrapper and its semantic role. -->
+<div
+  bind:this={stepElement}
+  use:observeStep
+  class={itemClass}
+  data-component-part="step-item"
+  id={id}
+  role="listitem"
+>
+  <div
+    class={cn(
+      "absolute top-11 h-[calc(100%-2.75rem)] w-px",
+      resolvedIsLast
+        ? "bg-linear-to-b from-stone-200 via-80% via-stone-200 to-transparent dark:from-white/10 dark:via-white/10 [[data-component-part=step-item]:has([data-component-part=step-content]:empty)_&]:hidden"
+        : "bg-stone-200/70 dark:bg-white/10"
+    )}
+    contenteditable="false"
+    data-component-part="step-line"
+  ></div>
+  <div
+    class="absolute ml-[-13px] py-2"
+    contenteditable="false"
+    data-component-part="step-number"
+  >
+    <!-- Svelte keeps the original hover target intact; the nested anchor remains the accessible control. -->
+    <!-- svelte-ignore a11y_no_static_element_interactions -->
+    <div
+      class="relative flex size-7 shrink-0 items-center justify-center rounded-full bg-stone-50 font-semibold text-stone-900 text-xs dark:bg-white/10 dark:text-stone-50"
+      onmouseenter={() => toggleAnchor(true)}
+      onmouseleave={() => toggleAnchor(false)}
+    >
+      <div class={cn(isTitleHovered && "opacity-0")}>
+        <!-- Svelte conditional branches replace the original nested icon ternary. -->
+        {#if typeof icon === "string"}
+          <Icon
+            class="size-3 bg-stone-900 dark:bg-stone-50"
+            icon={icon}
+            iconLibrary={iconLibrary}
+            iconType={iconType}
+            overrideColor={true}
+            overrideSize={true}
+          />
+        {:else if icon == null}
+          {Number(resolvedStepNumber)}
+        {:else}
+          {@render icon()}
+        {/if}
+      </div>
+      {#if isAnchorEnabled && !noAnchor && id}
+        <div class="absolute" data-component-part="step-number-anchor-link">
+          <a
+            aria-label="Navigate to header"
+            class={cn("flex items-center border-0 opacity-0", isTitleHovered && "opacity-100")}
+            href={`#${encodeURIComponent(id)}`}
+            onclick={(event) => {
+              event.preventDefault();
+              void copyAnchorLink();
+            }}
+          >
+            <div class="flex size-6 items-center justify-center">
+              <span aria-hidden="true" class="contents">
+                <Icon
+                  class="size-3 bg-stone-900 dark:bg-stone-50"
+                  icon="link"
+                  overrideColor={true}
+                  overrideSize={true}
+                />
+              </span>
+            </div>
+          </a>
+        </div>
+      {/if}
+    </div>
+  </div>
+  <div class="w-full overflow-hidden pr-px pl-8">
+    {#if title}
+      {#if titleTag === "h2"}
+        <!-- The title click handler preserves the original anchor-copy behavior without changing the heading element. -->
+        <!-- svelte-ignore a11y_click_events_have_key_events -->
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <h2
+          class={titleClasses}
+          contenteditable="false"
+          data-component-part="step-title"
+          onclick={() => void copyAnchorLink()}
+          onmouseenter={() => toggleAnchor(true)}
+          onmouseleave={() => toggleAnchor(false)}
+        >
+          {#if typeof title === "string"}{title}{:else}{@render title()}{/if}
+        </h2>
+      {:else if titleTag === "h3"}
+        <!-- svelte-ignore a11y_click_events_have_key_events -->
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <h3
+          class={titleClasses}
+          contenteditable="false"
+          data-component-part="step-title"
+          onclick={() => void copyAnchorLink()}
+          onmouseenter={() => toggleAnchor(true)}
+          onmouseleave={() => toggleAnchor(false)}
+        >
+          {#if typeof title === "string"}{title}{:else}{@render title()}{/if}
+        </h3>
+      {:else if titleTag === "h4"}
+        <!-- svelte-ignore a11y_click_events_have_key_events -->
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <h4
+          class={titleClasses}
+          contenteditable="false"
+          data-component-part="step-title"
+          onclick={() => void copyAnchorLink()}
+          onmouseenter={() => toggleAnchor(true)}
+          onmouseleave={() => toggleAnchor(false)}
+        >
+          {#if typeof title === "string"}{title}{:else}{@render title()}{/if}
+        </h4>
+      {:else}
+        <!-- svelte-ignore a11y_click_events_have_key_events -->
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <p
+          class={cn(titleClasses, "prose dark:prose-invert font-semibold")}
+          contenteditable="false"
+          data-component-part="step-title"
+          onclick={() => void copyAnchorLink()}
+          onmouseenter={() => toggleAnchor(true)}
+          onmouseleave={() => toggleAnchor(false)}
+        >
+          {#if typeof title === "string"}{title}{:else}{@render title()}{/if}
+        </p>
+      {/if}
+    {/if}
+    <div
+      class={cn("prose dark:prose-invert", !title && "mt-2")}
+      data-component-part="step-content"
+    >
+      {#if typeof children === "string"}
+        {children}
+      {:else if children}
+        {@render children()}
+      {/if}
+    </div>
+  </div>
+</div>

package/dist/components/steps/Step.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Snippet } from "svelte";
+import type { IconLibrary, IconType } from "../../utils/icon-utils";
+import { type StepTitleSize } from "./constants";
+type Numberish = number | `${number}`;
+type StepProps = {
+    icon?: string | Snippet;
+    stepNumber?: Numberish;
+    iconType?: IconType;
+    iconLibrary?: IconLibrary;
+    title: string | Snippet;
+    children?: string | Snippet;
+    titleSize?: StepTitleSize;
+    class?: string;
+    className?: string;
+    isLast?: boolean;
+    id?: string;
+    noAnchor?: boolean;
+    scrollElementIntoView?: (id: string) => void;
+    onCopyAnchorLink?: (id: string | undefined) => void;
+    onRegisterHeading?: (id: string, rect: DOMRect) => void;
+    onUnregisterHeading?: (id: string) => void;
+    _hasContext?: boolean;
+};
+declare const Step: import("svelte").Component<StepProps, {}, "">;
+type Step = ReturnType<typeof Step>;
+export default Step;

package/dist/components/steps/Steps.svelte

@@ -0,0 +1,51 @@
+<script lang="ts">
+  import { setContext } from "svelte";
+  import type { Snippet } from "svelte";
+  import { Classes } from "../../constants/selectors";
+  import { cn } from "../../utils/cn";
+  import { STEPS_CONTEXT, type StepsContext } from "./context";
+  import type { StepTitleSize } from "./constants";
+
+  type StepsProps = {
+    children?: Snippet;
+    titleSize?: StepTitleSize;
+    class?: string;
+    className?: string;
+  };
+
+  let {
+    children,
+    titleSize,
+    class: classAttribute,
+    className,
+  }: StepsProps = $props();
+
+  const stepsContext: StepsContext = $state({
+    items: [],
+    register(id) {
+      if (!stepsContext.items.includes(id)) {
+        stepsContext.items = [...stepsContext.items, id];
+      }
+    },
+    unregister(id) {
+      stepsContext.items = stepsContext.items.filter((itemId) => itemId !== id);
+    },
+  });
+
+  $effect(() => {
+    stepsContext.titleSize = titleSize;
+  });
+
+  setContext(STEPS_CONTEXT, stepsContext);
+</script>
+
+<!-- Svelte preserves the original list wrapper and its component-part contract. -->
+<div
+  class={cn(Classes.Steps, "mt-10 mb-6 ml-3.5", classAttribute ?? className)}
+  data-component-part="steps"
+  role="list"
+>
+  {#if children}
+    {@render children()}
+  {/if}
+</div>

package/dist/components/steps/Steps.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { Snippet } from "svelte";
+import type { StepTitleSize } from "./constants";
+type StepsProps = {
+    children?: Snippet;
+    titleSize?: StepTitleSize;
+    class?: string;
+    className?: string;
+};
+declare const Steps: import("svelte").Component<StepsProps, {}, "">;
+type Steps = ReturnType<typeof Steps>;
+export default Steps;

package/dist/components/steps/constants.d.ts

@@ -0,0 +1,4 @@
+declare const STEP_TITLE_SIZES: readonly ["p", "h2", "h3", "h4"];
+type StepTitleSize = (typeof STEP_TITLE_SIZES)[number];
+export { STEP_TITLE_SIZES };
+export type { StepTitleSize };

package/dist/components/steps/constants.js

@@ -0,0 +1,2 @@
+const STEP_TITLE_SIZES = ["p", "h2", "h3", "h4"];
+export { STEP_TITLE_SIZES };

package/dist/components/steps/context.d.ts

@@ -0,0 +1,10 @@
+import type { StepTitleSize } from "./constants";
+type StepsContext = {
+    items: symbol[];
+    titleSize?: StepTitleSize;
+    register: (id: symbol) => void;
+    unregister: (id: symbol) => void;
+};
+declare const STEPS_CONTEXT: unique symbol;
+export type { StepsContext };
+export { STEPS_CONTEXT };

package/dist/components/steps/context.js

@@ -0,0 +1,2 @@
+const STEPS_CONTEXT = Symbol("steps-context");
+export { STEPS_CONTEXT };