spoiler-ui 1.0.0

package/spoiler.js

@@ -0,0 +1,331 @@
+/**
+ * spoiler-ui
+ * A lightweight spoiler/content-reveal UI element — like Threads, Discord, Telegram.
+ * Vanilla JS, zero dependencies.
+ */
+
+const DEFAULTS = {
+  label: 'Spoiler',
+  blurAmount: 6,
+  revealOnClick: true,
+  animationDuration: 300,
+  className: '',
+  /** URL to fetch content from on reveal. When set, `content` param is optional. */
+  src: null,
+  /** Options passed directly to `fetch()`. Default: `{}` */
+  fetchOptions: {},
+  /** How to inject fetched content. 'html' uses innerHTML — XSS opt-in. Default: 'text' */
+  responseType: 'text',
+  /**
+   * When true, `content` is a Base64-encoded string. Decoded on reveal — never
+   * appears as plaintext in the DOM until the user clicks. Note: Base64 is
+   * obscurity, not encryption; a determined user can decode it from page source.
+   */
+  encoded: false,
+  /** Text shown on the pill while a fetch is in progress. Default: 'Loading…' */
+  loadingLabel: 'Loading\u2026',
+  /** Text shown on the pill when a fetch fails. Default: 'Failed — retry?' */
+  errorLabel: 'Failed \u2014 retry?',
+  /** Fired after successful reveal. Receives the revealed content string. */
+  onReveal: null,
+  /** Fired when a fetch or decode fails. Receives the Error object. */
+  onError: null,
+  /**
+   * Override the pill icon. Pass a string (emoji or character) to replace the
+   * default 👁, or `false`/`null` to hide the icon entirely.
+   */
+  icon: undefined,
+  /** Hide the pill label button (overlay + shimmer still show; click still reveals). */
+  showPill: true,
+};
+
+/**
+ * Decodes a Base64 string with full Unicode support.
+ * @param {string} b64
+ * @returns {string}
+ */
+export function decodeBase64(b64) {
+  const bytes = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+  return new TextDecoder().decode(bytes);
+}
+
+/**
+ * Encodes a string to Base64 with full Unicode support.
+ * Use this to prepare content before embedding it in your HTML or JS.
+ * @param {string} str
+ * @returns {string}
+ */
+export function encodeBase64(str) {
+  const bytes = new TextEncoder().encode(str);
+  let binary = '';
+  for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
+  return btoa(binary);
+}
+
+/**
+ * Creates a spoiler element wrapping the given content.
+ *
+ * @param {string|Element|null} content - Text or DOM element to hide (optional when `src` or `encoded` is set)
+ * @param {object} options
+ * @param {string}  [options.label='Spoiler']           - Label shown on the reveal button
+ * @param {number}  [options.blurAmount=6]              - px blur applied while hidden
+ * @param {boolean} [options.revealOnClick=true]        - Click anywhere to reveal; if false, only the button reveals
+ * @param {number}  [options.animationDuration=300]     - Transition duration in ms
+ * @param {string}  [options.className='']              - Extra CSS class on the root element
+ * @param {string}  [options.src]                       - URL to fetch content from on reveal
+ * @param {RequestInit} [options.fetchOptions={}]       - Options passed directly to fetch()
+ * @param {'text'|'html'} [options.responseType='text'] - How to inject fetched/decoded content
+ * @param {boolean} [options.encoded=false]             - Treat `content` as Base64; decode on reveal
+ * @param {function} [options.onReveal]                 - Callback fired after successful reveal
+ * @param {function} [options.onError]                  - Callback fired on fetch or decode failure; receives the Error
+ * @returns {HTMLElement}
+ */
+export function createSpoiler(content, options = {}) {
+  const opts = { ...DEFAULTS, ...options };
+
+  // State: 'idle' | 'loading' | 'error' | 'revealed'
+  let state = 'idle';
+  let isFetching = false;
+
+  const root = document.createElement('span');
+  root.className = ['spoiler-ui', opts.className].filter(Boolean).join(' ');
+  root.dataset.state = 'idle';
+  root.dataset.revealed = 'false';
+  root.style.setProperty('--spoiler-blur', `${opts.blurAmount}px`);
+  root.style.setProperty('--spoiler-duration', `${opts.animationDuration}ms`);
+
+  const inner = document.createElement('span');
+  inner.className = 'spoiler-ui__inner';
+
+  if (opts.encoded && typeof content === 'string') {
+    // Store encoded payload in data attr; inner gets a non-breaking space for height.
+    // Root gets data-empty → CSS inline-block + min-width so the absolute overlay
+    // has a proper rectangular containing block (inline parent isn't enough).
+    root.dataset.spoilerPayload = content;
+    root.dataset.empty = '';
+    inner.textContent = '\u00A0';
+  } else if (typeof content === 'string') {
+    inner.textContent = content;
+  } else if (content instanceof Element) {
+    inner.appendChild(content);
+  } else {
+    // src-only with no placeholder — same treatment
+    root.dataset.empty = '';
+    inner.textContent = '\u00A0';
+  }
+
+  // Icon customisation
+  if (opts.icon === false || opts.icon === null) {
+    root.dataset.noIcon = '';
+  } else if (typeof opts.icon === 'string') {
+    root.style.setProperty('--spoiler-icon', `'${opts.icon}'`);
+  }
+
+  // Pill visibility
+  if (!opts.showPill) root.dataset.noPill = '';
+
+  const overlay = document.createElement('span');
+  overlay.className = 'spoiler-ui__overlay';
+  overlay.setAttribute('role', 'button');
+  overlay.setAttribute('tabindex', '0');
+  overlay.setAttribute('aria-label', `Reveal ${opts.label}`);
+  overlay.setAttribute('aria-expanded', 'false');
+
+  const pill = document.createElement('span');
+  pill.className = 'spoiler-ui__pill';
+  pill.textContent = opts.label;
+
+  overlay.appendChild(pill);
+  root.appendChild(inner);
+  root.appendChild(overlay);
+
+  function setState(next) {
+    state = next;
+    root.dataset.state = next;
+
+    if (next === 'loading') {
+      pill.textContent = opts.loadingLabel;
+    } else if (next === 'error') {
+      pill.textContent = opts.errorLabel;
+    } else if (next === 'revealed') {
+      root.dataset.revealed = 'true';
+      delete root.dataset.spoilerPayload; // remove encoded payload from DOM
+      delete root.dataset.empty;          // content now in DOM, revert to inline
+      overlay.setAttribute('aria-hidden', 'true');
+      overlay.setAttribute('aria-expanded', 'true');
+      overlay.tabIndex = -1;
+      // Remove all event listeners — spoiler is terminal
+      root.removeEventListener('click', onRootClick);
+      root.removeEventListener('keydown', onRootKeydown);
+      overlay.removeEventListener('click', onOverlayClick);
+      overlay.removeEventListener('keydown', onOverlayKeydown);
+    }
+  }
+
+  function injectContent(text) {
+    if (opts.responseType === 'html') {
+      inner.innerHTML = text; // XSS opt-in — caller's responsibility
+    } else {
+      inner.textContent = text;
+    }
+  }
+
+  async function doFetch() {
+    if (isFetching) return;
+    isFetching = true;
+    setState('loading');
+
+    try {
+      const res = await fetch(opts.src, opts.fetchOptions);
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const text = await res.text();
+      injectContent(text);
+      isFetching = false;
+      setState('revealed');
+      opts.onReveal?.(text);
+    } catch (err) {
+      isFetching = false;
+      setState('error');
+      console.error('[spoiler-ui] Fetch failed:', err);
+      opts.onError?.(err);
+    }
+  }
+
+  function handleActivate() {
+    if (state === 'loading') return;
+    if (state !== 'idle' && state !== 'error') return;
+
+    if (opts.src) {
+      doFetch();
+    } else if (opts.encoded) {
+      const payload = root.dataset.spoilerPayload;
+      if (!payload) {
+        console.error('[spoiler-ui] Encoded mode enabled but no Base64 payload found. Pass a Base64 string as content.');
+        setState('error');
+        return;
+      }
+      try {
+        const decoded = decodeBase64(payload);
+        injectContent(decoded);
+        setState('revealed');
+        opts.onReveal?.(decoded);
+      } catch (err) {
+        console.error('[spoiler-ui] Failed to decode Base64 payload:', err);
+        setState('error');
+        opts.onError?.(err);
+      }
+    } else {
+      setState('revealed');
+      opts.onReveal?.(inner.textContent);
+    }
+  }
+
+  function onRootClick() { handleActivate(); }
+  function onRootKeydown(e) {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      handleActivate();
+    }
+  }
+  function onOverlayClick(e) {
+    e.stopPropagation();
+    handleActivate();
+  }
+  function onOverlayKeydown(e) {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      handleActivate();
+    }
+  }
+
+  if (opts.revealOnClick) {
+    root.addEventListener('click', onRootClick);
+    root.addEventListener('keydown', onRootKeydown);
+  } else {
+    overlay.addEventListener('click', onOverlayClick);
+    overlay.addEventListener('keydown', onOverlayKeydown);
+  }
+
+  return root;
+}
+
+/**
+ * Automatically initialises spoilers from `data-spoiler` attributes in the DOM.
+ *
+ * Supported attributes:
+ *   data-spoiler                  - Label text (enables the component)
+ *   data-spoiler-blur             - Blur amount in px
+ *   data-spoiler-duration         - Animation duration in ms
+ *   data-spoiler-src              - URL to fetch content from on reveal
+ *   data-spoiler-response-type    - 'text' (default) or 'html'
+ *   data-spoiler-encoded          - Base64-encoded content (decoded on reveal)
+ *   data-spoiler-reveal-on-click  - Set to 'false' to restrict reveal to pill button only
+ *   data-spoiler-class            - Extra CSS class added to the root element
+ *   data-spoiler-icon             - Pill icon: 'false' hides it, any string replaces the default 👁
+ *
+ * @param {Document|HTMLElement} [scope=document] - Root element to search within
+ */
+export function initSpoilers(scope = document) {
+  const els = scope.querySelectorAll('[data-spoiler]');
+
+  els.forEach((el) => {
+    const label = el.dataset.spoiler || DEFAULTS.label;
+
+    const blurRaw = Number(el.dataset.spoilerBlur);
+    const blur = Number.isFinite(blurRaw) ? blurRaw : DEFAULTS.blurAmount;
+
+    const durationRaw = Number(el.dataset.spoilerDuration);
+    const duration = Number.isFinite(durationRaw) ? durationRaw : DEFAULTS.animationDuration;
+
+    const src = el.dataset.spoilerSrc || null;
+    const encodedPayload = el.dataset.spoilerEncoded ?? null;
+    const responseType = el.dataset.spoilerResponseType === 'html' ? 'html' : 'text';
+    const revealOnClick = el.dataset.spoilerRevealOnClick !== 'false';
+    const showPill = el.dataset.spoilerShowPill !== 'false';
+    const loadingLabel = el.dataset.spoilerLoadingLabel ?? DEFAULTS.loadingLabel;
+    const errorLabel = el.dataset.spoilerErrorLabel ?? DEFAULTS.errorLabel;
+    const className = el.dataset.spoilerClass ?? '';
+
+    // icon: absent → undefined (CSS default), 'false' → false (hide), else string
+    const iconRaw = el.dataset.spoilerIcon;
+    const icon = iconRaw === undefined ? undefined : iconRaw === 'false' ? false : iconRaw;
+
+    if (encodedPayload && src) {
+      console.warn('[spoiler-ui] Both data-spoiler-encoded and data-spoiler-src are set — data-spoiler-src will be ignored.');
+    }
+
+    let contentArg = null;
+    let encoded = false;
+
+    if (encodedPayload) {
+      // Encoded mode: content comes from the data attribute, not from children
+      contentArg = encodedPayload;
+      encoded = true;
+    } else if (!src) {
+      // Move children directly — avoids innerHTML serialize/re-parse cycle
+      const wrapper = document.createElement('span');
+      while (el.firstChild) wrapper.appendChild(el.firstChild);
+      contentArg = wrapper;
+    }
+    // When src is set, existing children are discarded (server provides content)
+
+    const spoiler = createSpoiler(contentArg, {
+      label,
+      blurAmount: blur,
+      animationDuration: duration,
+      revealOnClick,
+      showPill,
+      loadingLabel,
+      errorLabel,
+      src,
+      responseType,
+      encoded,
+      className,
+      icon,
+    });
+
+    el.replaceWith(spoiler);
+  });
+}
+
+export { createSpoiler as default };

package/style.d.ts

@@ -0,0 +1,3 @@
+// Type declaration for the spoiler-ui/style CSS export.
+// Importing this file is a side-effect-only import that loads spoiler.css.
+declare module 'spoiler-ui/style' {}