@vizejs/composable 0.426.3 → 0.427.0

package/registry/files/use-script-tag.ts

@@ -0,0 +1,341 @@
+import { readonly, ref, shallowRef, toValue, watch } from "vue";
+import type { MaybeRefOrGetter, Ref, ShallowRef } from "vue";
+
+import { tryOnScopeDispose } from "./scope.ts";
+
+/** `<script>` subset used by {@link useScriptTag}. */
+export interface ScriptTagElement extends EventTarget {
+  /** Read an attribute. */
+  getAttribute(name: string): string | null;
+
+  /** Write an attribute. */
+  setAttribute(name: string, value: string): void;
+}
+
+/** Document capability used by {@link useScriptTag}. */
+export interface ScriptTagHost {
+  /** Find an existing `<script>` whose `src` attribute equals `src`. */
+  findScript(src: string): ScriptTagElement | undefined;
+
+  /** Create a detached `<script>`. */
+  createScript(): ScriptTagElement;
+
+  /** Attach a script to `<head>`, starting its download. */
+  append(element: ScriptTagElement): void;
+
+  /** Detach a script. */
+  remove(element: ScriptTagElement): void;
+}
+
+/** Loading state of the script. */
+export type ScriptTagStatus = "idle" | "loading" | "loaded" | "error";
+
+/** Discriminated outcome of {@link ScriptTagControls.load}. */
+export type ScriptTagResult =
+  | {
+      /** The script executed. */
+      readonly status: "loaded";
+      /** Script element. */
+      readonly element: ScriptTagElement;
+    }
+  | {
+      /** The script failed to load. */
+      readonly status: "error";
+      /** Script element. */
+      readonly element: ScriptTagElement;
+    }
+  | {
+      /** No document is available (server rendering) or the load was superseded. */
+      readonly status: "unsupported" | "cancelled";
+    };
+
+/** Options for {@link useScriptTag}. */
+export interface UseScriptTagOptions {
+  /**
+   * Called once the script has loaded.
+   *
+   * @default undefined
+   */
+  readonly onLoaded?: (element: ScriptTagElement) => void;
+
+  /**
+   * Load when created and whenever `src` changes.
+   *
+   * @default true
+   */
+  readonly immediate?: boolean;
+
+  /**
+   * Set the `async` attribute.
+   *
+   * @default true
+   */
+  readonly async?: boolean;
+
+  /**
+   * Set the `defer` attribute.
+   *
+   * @default false
+   */
+  readonly defer?: boolean;
+
+  /**
+   * Script `type` (for example `"module"`).
+   *
+   * @default "text/javascript"
+   */
+  readonly type?: string;
+
+  /**
+   * CORS mode (`crossorigin` attribute).
+   *
+   * @default undefined
+   */
+  readonly crossOrigin?: "anonymous" | "use-credentials";
+
+  /**
+   * Referrer policy.
+   *
+   * @default undefined
+   */
+  readonly referrerPolicy?: ReferrerPolicy;
+
+  /**
+   * Set the `nomodule` attribute.
+   *
+   * @default false
+   */
+  readonly noModule?: boolean;
+
+  /**
+   * CSP nonce.
+   *
+   * @default undefined
+   */
+  readonly nonce?: string;
+
+  /**
+   * Subresource integrity hash.
+   *
+   * @default undefined
+   */
+  readonly integrity?: string;
+
+  /**
+   * Additional attributes.
+   *
+   * @default {}
+   */
+  readonly attributes?: Readonly<Record<string, string>>;
+
+  /**
+   * Remove a script created by this composable when the owning scope stops.
+   *
+   * @default true
+   */
+  readonly removeOnDispose?: boolean;
+
+  /**
+   * Document capability for alternate runtimes and tests.
+   *
+   * @default window.document's `<head>`
+   */
+  readonly host?: MaybeRefOrGetter<ScriptTagHost | null | undefined>;
+}
+
+/** Reactive state and actions returned by {@link useScriptTag}. */
+export interface ScriptTagControls {
+  /** Loading state. */
+  readonly status: Readonly<Ref<ScriptTagStatus>>;
+
+  /** Script element in use, if any. */
+  readonly element: Readonly<ShallowRef<ScriptTagElement | undefined>>;
+
+  /**
+   * Load the script (or reuse an existing tag with the same `src`).
+   * Concurrent calls share one load; `unload` and scope disposal resolve a
+   * pending load as `"cancelled"`.
+   *
+   * @returns The discriminated outcome; never rejects.
+   */
+  readonly load: () => Promise<ScriptTagResult>;
+
+  /** Remove a script created by this composable and reset the state. */
+  readonly unload: () => void;
+}
+
+const STATUS_ATTRIBUTE = "data-vize-script-status";
+
+function browserScriptHost(): ScriptTagHost | undefined {
+  if (typeof window === "undefined") return undefined;
+  const { document, HTMLScriptElement, CSS } = window;
+  return {
+    findScript: (src) => {
+      const found = document.querySelector(`script[src="${CSS.escape(src)}"]`);
+      return found instanceof HTMLScriptElement ? found : undefined;
+    },
+    createScript: () => document.createElement("script"),
+    append: (element) => {
+      if (element instanceof HTMLScriptElement) document.head.append(element);
+    },
+    remove: (element) => {
+      if (element instanceof HTMLScriptElement) element.remove();
+    },
+  };
+}
+
+/**
+ * Inject a `<script>` tag and track its loading state.
+ *
+ * An existing tag with the same `src` is reused instead of duplicated: if
+ * it was created by another `useScriptTag` call its state is shared through
+ * a `data-vize-script-status` attribute; a tag without that attribute (for
+ * example emitted in server-rendered HTML) is assumed to have executed.
+ * Changing the reactive `src` unloads the previous script and, with
+ * `immediate`, loads the new one.
+ *
+ * Server rendering: no document exists, so nothing is injected, `status`
+ * stays `"idle"`, and `load` resolves `"unsupported"`. Emit server-side
+ * script tags through the application's head manager. Scripts created by
+ * this composable are removed when the owning scope stops (configurable);
+ * already-executed code cannot be unloaded.
+ *
+ * @example
+ * ```ts
+ * const { status } = useScriptTag("https://example.com/widget.js", {
+ *   onLoaded: () => window.Widget.init(),
+ * });
+ * ```
+ *
+ * @param src Reactive script URL.
+ * @param options Attributes, lifecycle, and capability.
+ * @default options {}
+ * @returns Loading state and actions.
+ */
+export function useScriptTag(
+  src: MaybeRefOrGetter<string>,
+  options: UseScriptTagOptions = {},
+): ScriptTagControls {
+  const status = ref<ScriptTagStatus>("idle");
+  const element = shallowRef<ScriptTagElement | undefined>(undefined);
+  let created = false;
+  let pending: Promise<ScriptTagResult> | undefined;
+  let generation = 0;
+  let cancelWait: (() => void) | undefined;
+
+  const resolveHost = (): ScriptTagHost | undefined =>
+    options.host === undefined ? browserScriptHost() : (toValue(options.host) ?? undefined);
+
+  const configure = (script: ScriptTagElement, url: string): void => {
+    script.setAttribute("type", options.type ?? "text/javascript");
+    if (options.async ?? true) script.setAttribute("async", "");
+    if (options.defer ?? false) script.setAttribute("defer", "");
+    if (options.noModule ?? false) script.setAttribute("nomodule", "");
+    if (options.crossOrigin !== undefined) script.setAttribute("crossorigin", options.crossOrigin);
+    if (options.referrerPolicy !== undefined) {
+      script.setAttribute("referrerpolicy", options.referrerPolicy);
+    }
+    if (options.nonce !== undefined) script.setAttribute("nonce", options.nonce);
+    if (options.integrity !== undefined) script.setAttribute("integrity", options.integrity);
+    for (const [name, value] of Object.entries(options.attributes ?? {})) {
+      script.setAttribute(name, value);
+    }
+    script.setAttribute(STATUS_ATTRIBUTE, "loading");
+    script.setAttribute("src", url);
+  };
+
+  const waitFor = (script: ScriptTagElement, current: number): Promise<ScriptTagResult> =>
+    new Promise((resolve) => {
+      const finish = (outcome: "loaded" | "error"): void => {
+        cancelWait = undefined;
+        script.removeEventListener("load", onLoad);
+        script.removeEventListener("error", onError);
+        script.setAttribute(STATUS_ATTRIBUTE, outcome);
+        if (current !== generation) {
+          resolve({ status: "cancelled" });
+          return;
+        }
+        status.value = outcome;
+        if (outcome === "loaded") options.onLoaded?.(script);
+        resolve({ status: outcome, element: script });
+      };
+      const onLoad = (): void => finish("loaded");
+      const onError = (): void => finish("error");
+      script.addEventListener("load", onLoad);
+      script.addEventListener("error", onError);
+      cancelWait = () => {
+        script.removeEventListener("load", onLoad);
+        script.removeEventListener("error", onError);
+        resolve({ status: "cancelled" });
+      };
+    });
+
+  const load = (): Promise<ScriptTagResult> => {
+    if (pending) return pending;
+    const host = resolveHost();
+    if (!host) return Promise.resolve({ status: "unsupported" });
+    const current = generation;
+    const url = toValue(src);
+    const existing = host.findScript(url);
+    if (existing) {
+      element.value = existing;
+      const state = existing.getAttribute(STATUS_ATTRIBUTE);
+      if (state === null || state === "loaded") {
+        status.value = "loaded";
+        options.onLoaded?.(existing);
+        return Promise.resolve({ status: "loaded", element: existing });
+      }
+      if (state === "error") {
+        status.value = "error";
+        return Promise.resolve({ status: "error", element: existing });
+      }
+    }
+    const script = existing ?? host.createScript();
+    status.value = "loading";
+    element.value = script;
+    const settled = waitFor(script, current).finally(() => {
+      if (pending === settled) pending = undefined;
+    });
+    pending = settled;
+    if (!existing) {
+      created = true;
+      configure(script, url);
+      host.append(script);
+    }
+    return settled;
+  };
+
+  const unload = (): void => {
+    generation += 1;
+    pending = undefined;
+    cancelWait?.();
+    cancelWait = undefined;
+    const script = element.value;
+    if (script && created) resolveHost()?.remove(script);
+    created = false;
+    element.value = undefined;
+    status.value = "idle";
+  };
+
+  if (options.immediate ?? true) {
+    watch(
+      () => toValue(src),
+      (_next, previous) => {
+        if (previous !== undefined) unload();
+        void load();
+      },
+      { immediate: true, flush: "sync" },
+    );
+  }
+
+  tryOnScopeDispose(() => {
+    if (options.removeOnDispose ?? true) {
+      unload();
+    } else {
+      generation += 1;
+      cancelWait?.();
+    }
+  });
+
+  return { status: readonly(status), element, load, unload };
+}

package/registry/files/use-segmenter.ts

@@ -0,0 +1,147 @@
+import { computed, toValue } from "vue";
+import type { ComputedRef, MaybeRefOrGetter } from "vue";
+
+import { useLocale } from "./locale.ts";
+
+/** Segmentation units supported by `Intl.Segmenter`. */
+export type SegmenterGranularity = "grapheme" | "word" | "sentence";
+
+/** One segment of the text. */
+export interface TextSegment {
+  /** Segment text. */
+  readonly segment: string;
+
+  /** UTF-16 code-unit offset of the segment in the source text. */
+  readonly index: number;
+
+  /** Word granularity: whether the segment is a word (not spaces or punctuation). */
+  readonly isWordLike: boolean;
+}
+
+/** Options for {@link useSegmenter}. */
+export interface UseSegmenterOptions {
+  /**
+   * Segmentation unit exposed through `segments` and `count`.
+   *
+   * @default "grapheme"
+   */
+  readonly granularity?: SegmenterGranularity;
+
+  /**
+   * Locale whose segmentation rules are used (word boundaries in Japanese or
+   * Thai depend on it). Pass it explicitly for hydration-stable output.
+   *
+   * @default the browser language, otherwise "en"
+   */
+  readonly locale?: string | Intl.Locale;
+}
+
+/** Reactive segmentation returned by {@link useSegmenter}. */
+export interface SegmenterControls {
+  /** Canonical locale in use. */
+  readonly locale: ComputedRef<string>;
+
+  /** Segments at the configured granularity. */
+  readonly segments: ComputedRef<readonly TextSegment[]>;
+
+  /** Number of segments at the configured granularity. */
+  readonly count: ComputedRef<number>;
+
+  /** User-perceived characters (grapheme clusters), independent of granularity. */
+  readonly graphemeCount: ComputedRef<number>;
+
+  /** Word-like segments, independent of granularity. */
+  readonly wordCount: ComputedRef<number>;
+
+  /**
+   * Truncate the text to at most `maxGraphemes` user-perceived characters,
+   * never splitting an emoji or combining sequence.
+   *
+   * @param maxGraphemes Maximum grapheme clusters kept, including the ellipsis.
+   * @param ellipsis Appended when the text was shortened.
+   * @default ellipsis "…"
+   * @returns The possibly truncated text.
+   * @throws {RangeError} `[VIZE_COMPOSE_SEGMENTER_INVALID_LENGTH]` for a
+   * negative or non-integer length.
+   */
+  readonly truncate: (maxGraphemes: number, ellipsis?: string) => string;
+}
+
+function browserLanguage(): string | undefined {
+  return typeof window === "undefined" ? undefined : window.navigator.language;
+}
+
+function toSegments(segmenter: Intl.Segmenter, text: string): readonly TextSegment[] {
+  return Array.from(segmenter.segment(text), (data) => ({
+    segment: data.segment,
+    index: data.index,
+    isWordLike: data.isWordLike ?? false,
+  }));
+}
+
+/**
+ * Split text into graphemes, words, or sentences with `Intl.Segmenter`.
+ *
+ * Counts reflect what users perceive: `"👨‍👩‍👧"` is one grapheme, and
+ * word counts skip spaces and punctuation while handling languages without
+ * spaces (Japanese, Thai) through the locale. `truncate` shortens text
+ * without splitting clusters. Derived state only; deterministic during
+ * server rendering when the locale is explicit.
+ *
+ * @example
+ * ```ts
+ * const { graphemeCount, truncate } = useSegmenter(bio, { locale: "en" });
+ * const remaining = computed(() => 160 - graphemeCount.value);
+ * ```
+ *
+ * @param text Reactive text.
+ * @param options Reactive granularity and locale.
+ * @default options {}
+ * @returns Reactive segments, counts, and truncation.
+ */
+export function useSegmenter(
+  text: MaybeRefOrGetter<string>,
+  options: MaybeRefOrGetter<UseSegmenterOptions> = {},
+): SegmenterControls {
+  const localeControls = useLocale(() => toValue(options).locale, { detect: browserLanguage });
+  const segmenterFor = (granularity: SegmenterGranularity) =>
+    computed(() => new Intl.Segmenter(localeControls.locale.value, { granularity }));
+  const graphemes = segmenterFor("grapheme");
+  const words = segmenterFor("word");
+  const sentences = segmenterFor("sentence");
+  const graphemeSegments = computed(() => toSegments(graphemes.value, toValue(text)));
+  const wordSegments = computed(() => toSegments(words.value, toValue(text)));
+  const segments = computed(() => {
+    const granularity = toValue(options).granularity ?? "grapheme";
+    if (granularity === "grapheme") return graphemeSegments.value;
+    if (granularity === "word") return wordSegments.value;
+    return toSegments(sentences.value, toValue(text));
+  });
+
+  const truncate = (maxGraphemes: number, ellipsis = "…"): string => {
+    if (!Number.isSafeInteger(maxGraphemes) || maxGraphemes < 0) {
+      throw new RangeError(
+        `[VIZE_COMPOSE_SEGMENTER_INVALID_LENGTH] maxGraphemes must be a non-negative integer; received ${String(maxGraphemes)}`,
+      );
+    }
+    const all = graphemeSegments.value;
+    if (all.length <= maxGraphemes) return toValue(text);
+    const ellipsisLength = toSegments(graphemes.value, ellipsis).length;
+    const keep = Math.max(0, maxGraphemes - ellipsisLength);
+    return (
+      all
+        .slice(0, keep)
+        .map((segment) => segment.segment)
+        .join("") + (maxGraphemes >= ellipsisLength ? ellipsis : "")
+    );
+  };
+
+  return {
+    locale: localeControls.locale,
+    segments,
+    count: computed(() => segments.value.length),
+    graphemeCount: computed(() => graphemeSegments.value.length),
+    wordCount: computed(() => wordSegments.value.filter((segment) => segment.isWordLike).length),
+    truncate,
+  };
+}