@ulearning/ai-generative-frame 0.0.0-stage → 1.0.0-next.0

package/src/vue/themeStore.ts

@@ -0,0 +1,157 @@
+import {
+  DEFAULT_LIGHT_TOKENS,
+  readThemeTokens,
+  type ThemeTokenSources,
+  type ThemeTokens,
+} from "../theme";
+
+export type ThemeObserveOptions = {
+  /**
+   * Also re-read when `<body>`'s `style` attribute changes. Off by default,
+   * because scroll-lock and dialog libraries rewrite it constantly; turn it on
+   * when the app sets theme variables through body styles.
+   */
+  observeBodyStyle?: boolean;
+};
+
+const THEME_ATTRIBUTES = ["class", "data-theme", "data-mode"];
+
+const sameTokens = (a: ThemeTokens, b: ThemeTokens) =>
+  a.colorScheme === b.colorScheme &&
+  JSON.stringify(a.variables) === JSON.stringify(b.variables);
+
+/** Runs `callback` on the next animation frame and returns a cancel function. */
+const nextFrame = (callback: () => void): (() => void) => {
+  if (typeof requestAnimationFrame === "function") {
+    const id = requestAnimationFrame(callback);
+    return () => cancelAnimationFrame(id);
+  }
+  const id = setTimeout(callback, 16);
+  return () => clearTimeout(id);
+};
+
+type Entry = {
+  tokens: ThemeTokens | undefined;
+  /** Snapshot read while nobody subscribes; valid for the current task. */
+  fresh: boolean;
+  listeners: Set<() => void>;
+  stop: (() => void) | undefined;
+};
+
+/**
+ * One reader per (element, sources, options): every subscriber shares one
+ * MutationObserver and one media listener, and a burst of mutations costs one
+ * `readThemeTokens` per animation frame.
+ */
+export function createThemeTokenStore(
+  target: Element,
+  sources: ThemeTokenSources,
+  options: ThemeObserveOptions,
+) {
+  const entry: Entry = {
+    tokens: undefined,
+    fresh: false,
+    listeners: new Set(),
+    stop: undefined,
+  };
+
+  const read = () => {
+    const next = readThemeTokens(target, sources);
+    if (entry.tokens && sameTokens(entry.tokens, next)) return false;
+    entry.tokens = next;
+    return true;
+  };
+
+  const start = () => {
+    let cancelFrame: (() => void) | undefined;
+    const update = () => {
+      cancelFrame = undefined;
+      if (read()) for (const listener of entry.listeners) listener();
+    };
+    const schedule = () => {
+      cancelFrame ??= nextFrame(update);
+    };
+    const doc = target.ownerDocument;
+    const observer = new MutationObserver(schedule);
+    observer.observe(doc.documentElement, {
+      attributes: true,
+      attributeFilter: [...THEME_ATTRIBUTES, "style"],
+    });
+    if (doc.body) {
+      observer.observe(doc.body, {
+        attributes: true,
+        attributeFilter: options.observeBodyStyle
+          ? [...THEME_ATTRIBUTES, "style"]
+          : THEME_ATTRIBUTES,
+      });
+    }
+    if (target !== doc.documentElement && target !== doc.body) {
+      observer.observe(target, {
+        attributes: true,
+        attributeFilter: [...THEME_ATTRIBUTES, "style"],
+      });
+    }
+    const media = doc.defaultView?.matchMedia?.("(prefers-color-scheme: dark)");
+    media?.addEventListener("change", schedule);
+    // Anything that changed between the last read and now.
+    schedule();
+    return () => {
+      observer.disconnect();
+      media?.removeEventListener("change", schedule);
+      cancelFrame?.();
+    };
+  };
+
+  return {
+    subscribe(listener: () => void) {
+      entry.listeners.add(listener);
+      entry.stop ??= start();
+      return () => {
+        entry.listeners.delete(listener);
+        if (entry.listeners.size === 0) {
+          entry.stop?.();
+          entry.stop = undefined;
+          entry.fresh = false;
+        }
+      };
+    },
+    getSnapshot(): ThemeTokens {
+      if (entry.stop && entry.tokens) return entry.tokens;
+      if (!entry.fresh) {
+        read();
+        entry.fresh = true;
+        queueMicrotask(() => {
+          entry.fresh = false;
+        });
+      }
+      return entry.tokens ?? DEFAULT_LIGHT_TOKENS;
+    },
+    get subscribers() {
+      return entry.listeners.size;
+    },
+  };
+}
+
+export type ThemeTokenStore = ReturnType<typeof createThemeTokenStore>;
+
+const stores = new WeakMap<Element, Map<string, ThemeTokenStore>>();
+
+/** The shared store for this element, sources, and options. */
+export function getThemeTokenStore(
+  target: Element,
+  sources: ThemeTokenSources = {},
+  options: ThemeObserveOptions = {},
+): ThemeTokenStore {
+  const key = JSON.stringify([sources, options.observeBodyStyle ?? false]);
+  let byKey = stores.get(target);
+  if (!byKey) {
+    byKey = new Map();
+    stores.set(target, byKey);
+  }
+  let store = byKey.get(key);
+  if (!store) {
+    store = createThemeTokenStore(target, sources, options);
+    byKey.set(key, store);
+  }
+  return store;
+}

package/src/vue/useThemeTokens.ts

@@ -0,0 +1,71 @@
+import {
+  onActivated,
+  onBeforeUnmount,
+  onDeactivated,
+  onMounted,
+  onServerPrefetch,
+  readonly,
+  shallowRef,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type ShallowRef,
+} from "vue";
+import {
+  DEFAULT_LIGHT_TOKENS,
+  type ThemeTokenSources,
+  type ThemeTokens,
+} from "../theme";
+import { getThemeTokenStore, type ThemeObserveOptions } from "./themeStore";
+/** One shared observer per element/source/options; subscriptions follow the component lifecycle. */
+export function useThemeTokens(
+  element?: MaybeRefOrGetter<Element | null | undefined>,
+  sources?: ThemeTokenSources,
+  options: ThemeObserveOptions = {},
+): Readonly<ShallowRef<ThemeTokens>> {
+  const target = () =>
+    toValue(element) ??
+    (typeof document === "undefined" ? undefined : document.documentElement);
+  const tokens = shallowRef(
+    target()
+      ? getThemeTokenStore(target()!, sources, options).getSnapshot()
+      : DEFAULT_LIGHT_TOKENS,
+  );
+  let stop: (() => void) | undefined;
+  let active = false;
+  const disconnect = () => {
+    stop?.();
+    stop = undefined;
+  };
+  const connect = () => {
+    disconnect();
+    const current = target();
+    if (!active || !current) return;
+    const store = getThemeTokenStore(current, sources, options);
+    tokens.value = store.getSnapshot();
+    stop = store.subscribe(() => {
+      tokens.value = store.getSnapshot();
+    });
+  };
+  onServerPrefetch(() => {
+    tokens.value = DEFAULT_LIGHT_TOKENS;
+  });
+  onMounted(() => {
+    active = true;
+    connect();
+  });
+  onActivated(() => {
+    active = true;
+    connect();
+  });
+  onDeactivated(() => {
+    active = false;
+    disconnect();
+  });
+  onBeforeUnmount(() => {
+    active = false;
+    disconnect();
+  });
+  watch(target, connect, { flush: "post" });
+  return readonly(tokens);
+}

package/src/vue/useWidget.ts

@@ -0,0 +1,117 @@
+import {
+  onActivated,
+  onBeforeUnmount,
+  onDeactivated,
+  onMounted,
+  shallowReadonly,
+  shallowRef,
+  toValue,
+  watch,
+  type ComponentPublicInstance,
+  type MaybeRefOrGetter,
+  type ShallowRef,
+} from "vue";
+import { RPC_ERROR, RpcError } from "../rpc";
+import {
+  createWidget,
+  type CreateWidgetOptions,
+  type WidgetHandle,
+  type WidgetHandlers,
+} from "../widget";
+
+export type UseWidgetOptions = Omit<CreateWidgetOptions, "container" | "code">;
+export type UseWidgetResult = {
+  ref: (element: Element | ComponentPublicInstance | null) => void;
+  widget: Readonly<ShallowRef<WidgetHandle | null>>;
+};
+const HANDLER_KEYS = Object.keys({
+  onPrompt: true,
+  onMessage: true,
+  onOpenLink: true,
+  onCallTool: true,
+  onInitialized: true,
+  onRequestDisplayMode: true,
+  onUpdateModelContext: true,
+  onCopyText: true,
+  onWidgetState: true,
+  onResize: true,
+  onError: true,
+  onLog: true,
+} satisfies Record<keyof WidgetHandlers, true>) as (keyof WidgetHandlers)[];
+
+/** Mount options are read per activation. Handlers and tokens follow the latest options. */
+export function useWidget(
+  options: MaybeRefOrGetter<UseWidgetOptions> = {},
+): UseWidgetResult {
+  const element = shallowRef<HTMLElement | null>(null);
+  const active = shallowRef(false);
+  const widget = shallowRef<WidgetHandle | null>(null);
+  let widgetState: { value: unknown } | undefined;
+  let sentTokens: UseWidgetOptions["tokens"];
+  onMounted(() => {
+    active.value = true;
+  });
+  onActivated(() => {
+    active.value = true;
+  });
+  onDeactivated(() => {
+    active.value = false;
+  });
+  onBeforeUnmount(() => {
+    active.value = false;
+  });
+  watch(
+    [element, active],
+    ([container, enabled], _previous, onCleanup) => {
+      if (!container || !enabled) return;
+      const initial = toValue(options);
+      const handlers: Record<string, unknown> = {};
+      for (const key of HANDLER_KEYS) {
+        if (!initial[key]) continue;
+        handlers[key] = (...args: unknown[]) => {
+          const handler = toValue(options)[key] as
+            | ((...args: unknown[]) => unknown)
+            | undefined;
+          if (!handler)
+            throw new RpcError(
+              RPC_ERROR.methodNotFound,
+              `${key} is no longer handled`,
+            );
+          return handler(...args);
+        };
+      }
+      const handle = createWidget({
+        ...initial,
+        ...(handlers as WidgetHandlers),
+        ...(widgetState ? { initialState: widgetState.value } : {}),
+        onWidgetState: (state) => {
+          widgetState = { value: state };
+          toValue(options).onWidgetState?.(state);
+        },
+        container,
+      });
+      sentTokens = initial.tokens;
+      widget.value = handle;
+      onCleanup(() => {
+        widget.value = null;
+        handle.dispose();
+      });
+    },
+    { flush: "sync" },
+  );
+  watch(
+    () => toValue(options).tokens,
+    (tokens) => {
+      if (!widget.value || !tokens || sentTokens === tokens) return;
+      sentTokens = tokens;
+      widget.value.setTheme(tokens);
+    },
+    { flush: "post" },
+  );
+  return {
+    ref: (next) => {
+      element.value = next instanceof HTMLElement ? next : null;
+    },
+    widget: shallowReadonly(widget),
+  };
+}

package/src/vue.ts

@@ -0,0 +1,8 @@
+export { Widget, type WidgetProps } from "./vue/Widget";
+export {
+  useWidget,
+  type UseWidgetOptions,
+  type UseWidgetResult,
+} from "./vue/useWidget";
+export { useThemeTokens } from "./vue/useThemeTokens";
+export type { ThemeObserveOptions } from "./vue/themeStore";