@learncard/react 2.10.2 → 2.10.4

package/src/helpers/useHorizontalPages.ts

@@ -0,0 +1,130 @@
+import { RefObject, useEffect, useRef, useState } from 'react';
+
+type ScrollTo<T extends Object> = Record<
+    keyof T,
+    (smooth?: boolean, options?: ScrollIntoViewOptions) => void
+>;
+
+type On<T extends Object> = Record<keyof T, boolean>;
+
+type UseHorizontalPages = <
+    T extends Record<string, RefObject<Element>> = Record<string, RefObject<Element>>,
+    K extends keyof T = keyof T
+>(args: {
+    /** Object with names as keys and refs as values, with each ref attached to a page */
+    refs: T;
+    /** Minimum time in between state updates for the on object */
+    throttleTime?: number;
+    /** Options to pass into IntersectionObserver constructor */
+    options?: IntersectionObserverInit;
+    /** If set to false, you must manually call observe to start IntersectionObservers */
+    observeImmediately?: boolean;
+}) => {
+    on: Record<K, boolean>;
+    scrollTo: Record<K, (smooth?: boolean, options?: ScrollIntoViewOptions) => void>;
+    observe: () => void;
+    unobserve: () => void;
+};
+
+/**
+ * React hook for displaying horizontal pages. This works very well in tandem with CSS Scroll Snap
+ * for displaying rich interfaces that can be scrolled via swiping left/right or via buttons
+ *
+ * To use it, pass in an object of named refs (e.g. { test1: ref1, test2: ref2 }) and attach those
+ * refs to your pages (e.g. <section><article ref={ref1} /><article ref={ref2} /></section>)
+ *
+ * With the above set up, you can scroll to any page using scrollTo[nameOfRef] (e.g. scrollTo.test1),
+ * and you may also check whether a given page is visible using on[nameOfRef] (e.g. on.test2).
+ *
+ * Names are generated automatically based upon the refs object you pass in, and on and scrollTo are
+ * both fully type safe, meaning your editor should give you accurate autocompletion hints, and
+ * should also warn you if you accidentally mistype a name!
+ *
+ * Example:
+ * const Test = () => {
+ *   const refs = { page1: useRef<HTMLElement>(null), page2: useRef<HTMLElement>(null) };
+ *   const { on, scrollTo } = useHorizontalPages({ refs });
+ *
+ *   return (
+ *       <main>
+ *           <header>
+ *               <button type="button" onClick={() => on.page1 ? scrollTo.page2 : scrollTo.page1}>
+ *               {`Scroll to ${on.page1 ? 'Page 2' : 'Page 1'}`}
+ *               </button>
+ *           </header>
+ *           <section>
+ *               <article ref={page1}>
+ *               <article ref={page2>}
+ *           </section>
+ *       </main>
+ *   )
+ * }
+ *
+ * If needed, you can also use observe/unobserve to dynamically add/delete pages as well
+ */
+const useHorizontalPages: UseHorizontalPages = ({
+    refs,
+    options = {},
+    observeImmediately = true,
+}) => {
+    const [on, setOn] = useState(
+        Object.keys(refs).reduce<On<typeof refs>>(
+            (acc, name) => ({ ...acc, [name]: false }),
+            (<unknown>{}) as On<typeof refs>
+        )
+    );
+
+    const observer = useRef<Record<string, IntersectionObserver>>({});
+
+    const getObserver = (name: string) => {
+        if (observer.current[name] === undefined) {
+            observer.current[name] = new IntersectionObserver(
+                ([entry]) => setOn(oldOn => ({ ...oldOn, [name]: entry.isIntersecting })),
+                { rootMargin: '0px', threshold: 0.1, ...options }
+            );
+        }
+
+        return observer.current[name];
+    };
+
+    const scrollTo = Object.entries(refs).reduce<ScrollTo<typeof refs>>((acc, [name, ref]) => {
+        acc[<keyof typeof refs>name] = (
+            smooth: boolean = true,
+            overrides: ScrollIntoViewOptions = {}
+        ) => ref.current?.scrollIntoView({ behavior: smooth ? 'smooth' : 'auto', ...overrides });
+
+        return acc;
+    }, (<unknown>{}) as ScrollTo<typeof refs>);
+
+    const unobserve = () => {
+        Object.keys(refs).forEach(name => {
+            getObserver(name).disconnect();
+        });
+    };
+
+    const observe = () => {
+        Object.entries(refs).forEach(([name, ref]) => {
+            if (ref.current) getObserver(name).observe(ref.current);
+        });
+    };
+
+    useEffect(() => {
+        unobserve();
+        if (observeImmediately) observe();
+
+        return unobserve;
+    }, [
+        // Placing a raw object in the dependencies array here will cause this effect to constantly
+        // re-run (unless you memoize the actual object passed in)
+        // To be able to account for a given ref changing (e.g. a page being conditionally rendered),
+        // we need to serialize the refs object and convert it to a primitive type that will change
+        // when the ref values change
+        Object.values(refs)
+            .map(ref => !!ref.current)
+            .join(),
+    ]);
+
+    return { on, scrollTo, observe, unobserve };
+};
+
+export default useHorizontalPages;

package/src/helpers/useOnMomentumScrollEnd.ts

@@ -0,0 +1,28 @@
+import React, { useEffect, useRef } from 'react';
+
+export const useOnMomentumScrollEnd = ({
+    onScroll: _onScroll,
+    onMomentumScrollEnd,
+    debounceTime = 305,
+}: {
+    onScroll?: React.UIEventHandler;
+    onMomentumScrollEnd: React.UIEventHandler;
+    debounceTime?: number;
+}) => {
+    const momentumScrollEndTimer = useRef<NodeJS.Timeout>();
+
+    useEffect(() => () => clearTimeout(momentumScrollEndTimer.current), []);
+
+    const onScroll: React.UIEventHandler = (e) => {
+        _onScroll?.(e);
+
+        clearTimeout(momentumScrollEndTimer.current);
+        momentumScrollEndTimer.current = setTimeout(() => {
+            onMomentumScrollEnd(e);
+        }, debounceTime);
+    };
+
+    return onScroll;
+};
+
+export default useOnMomentumScrollEnd;

package/src/helpers/useScrollBorders.ts

@@ -0,0 +1,59 @@
+import React, { useEffect, type RefObject } from 'react';
+
+export const useScrollBorders = <Ref extends HTMLElement>({
+    ref,
+    topShowClassName = 'border-t border-t-[--color-grayscale-line]',
+    topHideClassName = 'border-t border-t-transparent',
+    bottomShowClassName = 'border-b border-b-[--color-grayscale-line]',
+    bottomHideClassName = 'border-b border-b-transparent',
+}: {
+    ref?: RefObject<Ref>;
+    topShowClassName?: string;
+    topHideClassName?: string;
+    bottomShowClassName?: string;
+    bottomHideClassName?: string;
+} = {}) => {
+    const internalRef = ref ?? React.createRef<Ref>();
+
+    const updateBorderClasses = () => {
+        if (
+            !internalRef.current ||
+            internalRef.current.scrollHeight <= internalRef.current.clientHeight
+        )
+            return;
+
+        // Top border
+        if (internalRef.current.scrollTop > 0) {
+            internalRef.current.classList.remove(...topHideClassName.split(' '));
+            internalRef.current.classList.add(...topShowClassName.split(' '));
+        } else {
+            internalRef.current.classList.remove(...topShowClassName.split(' '));
+            internalRef.current.classList.add(...topHideClassName.split(' '));
+        }
+
+        // Bottom border
+        if (
+            internalRef.current.scrollTop <
+            internalRef.current.scrollHeight - internalRef.current.clientHeight
+        ) {
+            internalRef.current.classList.remove(...bottomHideClassName.split(' '));
+            internalRef.current.classList.add(...bottomShowClassName.split(' '));
+        } else {
+            internalRef.current.classList.remove(...bottomShowClassName.split(' '));
+            internalRef.current.classList.add(...bottomHideClassName.split(' '));
+        }
+    };
+
+    useEffect(() => {
+        const element = internalRef.current;
+        if (element) {
+            updateBorderClasses();
+
+            element.addEventListener('scroll', updateBorderClasses);
+
+            return () => element.removeEventListener('scroll', updateBorderClasses);
+        }
+    }, [internalRef]); // Re-run when ref changes
+
+    return internalRef;
+};

package/src/helpers/video.helpers.ts

@@ -0,0 +1,125 @@
+export type VideoPlatform = 'youtube' | 'vimeo' | 'drive' | 'loom' | 'unknown';
+
+export type VideoMetadata = {
+    type: VideoPlatform;
+    videoId: string | null;
+    embedUrl: string | null;
+    thumbnailUrl: string | null;
+};
+
+export const getVideoMetadata = async (url: string): Promise<VideoMetadata> => {
+    try {
+        const parsed = new URL(url);
+        const host = parsed.hostname.replace(/^www\./, '');
+        let id: string | null = null;
+
+        // YouTube
+        if (host === 'youtu.be' || host.includes('youtube.com')) {
+            if (host === 'youtu.be') {
+                id = parsed.pathname.slice(1);
+            } else {
+                id =
+                    parsed.searchParams.get('v') ||
+                    parsed.pathname.split('/').filter(Boolean).pop() ||
+                    null;
+            }
+            if (id) {
+                let thumb = `https://img.youtube.com/vi/${id}/maxresdefault.jpg`;
+                try {
+                    const res = await fetch(thumb, { method: 'HEAD' });
+                    if (!res.ok) thumb = `https://img.youtube.com/vi/${id}/hqdefault.jpg`;
+                } catch {
+                    thumb = `https://img.youtube.com/vi/${id}/hqdefault.jpg`;
+                }
+                return {
+                    type: 'youtube',
+                    videoId: id,
+                    embedUrl: `https://www.youtube.com/embed/${id}`,
+                    thumbnailUrl: thumb,
+                };
+            }
+        }
+
+        // Vimeo
+        if (host.includes('vimeo.com')) {
+            const match = url.match(/vimeo\.com\/(\d+)/);
+            id = match?.[1] ?? null;
+            if (id) {
+                try {
+                    const oembed = `https://vimeo.com/api/oembed.json?url=${encodeURIComponent(
+                        url
+                    )}`;
+                    const data = await fetch(oembed).then(r => r.json());
+                    return {
+                        type: 'vimeo',
+                        videoId: id,
+                        embedUrl: `https://player.vimeo.com/video/${id}`,
+                        thumbnailUrl: data.thumbnail_url,
+                    };
+                } catch (e) {
+                    // Fallback if oEmbed fails
+                    return {
+                        type: 'vimeo',
+                        videoId: id,
+                        embedUrl: `https://player.vimeo.com/video/${id}`,
+                        thumbnailUrl: null,
+                    };
+                }
+            }
+        }
+
+        // Google Drive
+        if (host === 'drive.google.com' || host === 'docs.google.com') {
+            const match = parsed.pathname.match(/\/d\/([^/]+)/);
+            id = match?.[1] ?? parsed.searchParams.get('id');
+            if (id) {
+                return {
+                    type: 'drive',
+                    videoId: id,
+                    embedUrl: `https://drive.google.com/file/d/${id}/preview`,
+                    thumbnailUrl: `https://drive.google.com/thumbnail?sz=w320-h320&id=${id}`,
+                };
+            }
+        }
+
+        // Loom
+        if (host === 'loom.com') {
+            const match = parsed.pathname.match(/\/(?:share|embed|watch)\/([A-Za-z0-9]+)/);
+            id = match?.[1] ?? null;
+            if (id) {
+                const embedUrl = `https://www.loom.com/embed/${id}`;
+                try {
+                    const oembedUrl = `https://www.loom.com/api/oembed?url=${encodeURIComponent(
+                        url
+                    )}`;
+                    const response = await fetch(oembedUrl);
+                    if (!response.ok) {
+                        throw new Error(`oEmbed API returned ${response.status}`);
+                    }
+                    const data = await response.json();
+                    return {
+                        type: 'loom',
+                        videoId: id,
+                        embedUrl,
+                        thumbnailUrl: data.thumbnail_url,
+                    };
+                } catch (e) {
+                    // Fallback if oEmbed fails
+                    console.warn('Loom oEmbed fetch failed:', e);
+                    return {
+                        type: 'loom',
+                        videoId: id,
+                        embedUrl,
+                        thumbnailUrl: null,
+                    };
+                }
+            }
+        }
+
+        // Fallback
+        return { type: 'unknown', videoId: null, embedUrl: null, thumbnailUrl: null };
+    } catch (e) {
+        console.error('getVideoMetadata error:', e);
+        return { type: 'unknown', videoId: null, embedUrl: null, thumbnailUrl: null };
+    }
+};

package/src/hooks/useCredentialFormat.tsx

@@ -0,0 +1,23 @@
+import { useMemo } from 'react';
+
+export type CredentialFormat = 'dc+sd-jwt' | 'vc+sd-jwt' | 'jwt-vc-json' | 'ldp-vc' | 'unknown';
+
+export const useCredentialFormat = (vc: unknown): CredentialFormat => {
+    return useMemo(() => {
+        if (!vc || typeof vc !== 'object') return 'unknown';
+        const proof = (vc as any).proof;
+        const proofs: any[] = Array.isArray(proof) ? proof : proof ? [proof] : [];
+
+        const sdJwt = proofs.find(
+            p => p?.type === 'SdJwtCompactProof' && typeof p?.jwt === 'string'
+        );
+        if (sdJwt) return 'dc+sd-jwt';
+
+        const proofObj = proofs.find(p => p && typeof p === 'object');
+        if (typeof proofObj?.jwt === 'string' || proofObj?.type === 'JwtProof2020') {
+            return 'jwt-vc-json';
+        }
+        if (typeof proofObj?.type === 'string') return 'ldp-vc';
+        return 'unknown';
+    }, [vc]);
+};

package/src/hooks/useParsedSdJwtVc.tsx

@@ -0,0 +1,64 @@
+import { useState, useEffect } from 'react';
+import { LearnCard } from '@learncard/core';
+
+export type ParsedSdJwtVc = {
+    vct: string;
+    issuer: string;
+    issuedAt?: Date;
+    expiresAt?: Date;
+    notBefore?: Date;
+    holderPublicKey?: Record<string, unknown>;
+    claims: Record<string, unknown>;
+    disclosureKeys: string[];
+    header: Record<string, unknown>;
+    rawPayload: Record<string, unknown>;
+    rawSdJwt: string;
+    format: 'dc+sd-jwt' | 'vc+sd-jwt';
+    hasKeyBinding: boolean;
+};
+
+export const useParsedSdJwtVc = (learnCard: LearnCard | undefined, compact: string | undefined) => {
+    const [data, setData] = useState<ParsedSdJwtVc | undefined>(undefined);
+    const [isLoading, setIsLoading] = useState<boolean>(false);
+    const [error, setError] = useState<Error | undefined>(undefined);
+
+    useEffect(() => {
+        let cancelled = false;
+
+        if (!learnCard || !compact) {
+            setData(undefined);
+            setIsLoading(false);
+            setError(undefined);
+            return;
+        }
+
+        const parse = async () => {
+            setIsLoading(true);
+            setError(undefined);
+            setData(undefined);
+            try {
+                const parsed = await (learnCard.invoke as any).parseSdJwtVc(compact);
+                if (!cancelled) {
+                    setData(parsed as ParsedSdJwtVc);
+                }
+            } catch (err) {
+                if (!cancelled) {
+                    setData(undefined);
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                }
+            } finally {
+                if (!cancelled) {
+                    setIsLoading(false);
+                }
+            }
+        };
+
+        parse();
+
+        return () => {
+            cancelled = true;
+        };
+    }, [learnCard, compact]);
+
+    return { data, isLoading, error };
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+/// <reference path="./declaration.d.ts" />
+
+export * from './components/index';
+
+// Export shared hooks
+export * from './helpers/useHorizontalPages';
+export * from './helpers/useOnMomentumScrollEnd';
+export * from './helpers/useScrollBorders';
+
+// Export DID display helpers
+export * from './helpers/did-display.helpers';
+
+// Export SD-JWT-VC hooks and helpers
+export * from './hooks/useCredentialFormat';
+export * from './hooks/useParsedSdJwtVc';
+export * from './helpers/credentialFormat.helpers';