@miozu/jera 0.0.2 → 0.4.2

package/src/actions/index.js

@@ -0,0 +1,375 @@
+/**
+ * Svelte Actions Library
+ *
+ * Reusable element behaviors that can be composed onto any element.
+ * Actions are the Svelte way to add imperative logic to elements.
+ *
+ * @example
+ * <div use:clickOutside={handleClose}>...</div>
+ * <input use:focus />
+ * <button use:longPress={{ duration: 500, onLongPress: handler }}>...</button>
+ */
+
+/**
+ * Click Outside Action
+ *
+ * Fires callback when clicking outside the element.
+ * Useful for dropdowns, modals, popovers.
+ *
+ * @param {HTMLElement} node
+ * @param {() => void} callback
+ * @returns {{ destroy: () => void, update: (cb: () => void) => void }}
+ *
+ * @example
+ * <div use:clickOutside={() => isOpen = false}>Dropdown</div>
+ */
+export function clickOutside(node, callback) {
+  let handler = callback;
+
+  function handleClick(event) {
+    if (!node.contains(event.target) && !event.defaultPrevented) {
+      handler?.();
+    }
+  }
+
+  // Use mousedown for better UX (fires before focus changes)
+  document.addEventListener('mousedown', handleClick, true);
+
+  return {
+    update(newCallback) {
+      handler = newCallback;
+    },
+    destroy() {
+      document.removeEventListener('mousedown', handleClick, true);
+    }
+  };
+}
+
+/**
+ * Focus Trap Action
+ *
+ * Traps focus within an element. Essential for accessible modals.
+ *
+ * @param {HTMLElement} node
+ * @param {{ enabled?: boolean, initialFocus?: string }} [options]
+ * @returns {{ destroy: () => void, update: (opts: { enabled?: boolean }) => void }}
+ *
+ * @example
+ * <dialog use:focusTrap={{ enabled: isOpen }}>...</dialog>
+ */
+export function focusTrap(node, options = {}) {
+  let { enabled = true, initialFocus } = options;
+
+  const focusableSelectors = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])'
+  ].join(',');
+
+  function getFocusable() {
+    return Array.from(node.querySelectorAll(focusableSelectors));
+  }
+
+  function handleKeydown(event) {
+    if (!enabled || event.key !== 'Tab') return;
+
+    const focusable = getFocusable();
+    if (focusable.length === 0) return;
+
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+
+    if (event.shiftKey && document.activeElement === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && document.activeElement === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  }
+
+  function setInitialFocus() {
+    if (!enabled) return;
+
+    const target = initialFocus
+      ? node.querySelector(initialFocus)
+      : getFocusable()[0];
+
+    target?.focus();
+  }
+
+  node.addEventListener('keydown', handleKeydown);
+  // Delay initial focus to allow transitions
+  requestAnimationFrame(setInitialFocus);
+
+  return {
+    update(newOptions) {
+      enabled = newOptions.enabled ?? true;
+      initialFocus = newOptions.initialFocus;
+      if (enabled) setInitialFocus();
+    },
+    destroy() {
+      node.removeEventListener('keydown', handleKeydown);
+    }
+  };
+}
+
+/**
+ * Auto-focus Action
+ *
+ * Focuses element on mount.
+ *
+ * @param {HTMLElement} node
+ * @param {{ delay?: number, select?: boolean }} [options]
+ *
+ * @example
+ * <input use:autoFocus />
+ * <input use:autoFocus={{ delay: 100, select: true }} />
+ */
+export function autoFocus(node, options = {}) {
+  const { delay = 0, select = false } = options;
+
+  const timeout = setTimeout(() => {
+    node.focus();
+    if (select && 'select' in node) {
+      node.select();
+    }
+  }, delay);
+
+  return {
+    destroy() {
+      clearTimeout(timeout);
+    }
+  };
+}
+
+/**
+ * Long Press Action
+ *
+ * Detects long press/hold gesture.
+ *
+ * @param {HTMLElement} node
+ * @param {{ duration?: number, onLongPress: () => void }} options
+ *
+ * @example
+ * <button use:longPress={{ duration: 500, onLongPress: handleLongPress }}>
+ *   Hold me
+ * </button>
+ */
+export function longPress(node, options) {
+  let { duration = 500, onLongPress } = options;
+  let timeout = null;
+
+  function handleStart() {
+    timeout = setTimeout(() => {
+      onLongPress?.();
+    }, duration);
+  }
+
+  function handleEnd() {
+    if (timeout) {
+      clearTimeout(timeout);
+      timeout = null;
+    }
+  }
+
+  node.addEventListener('mousedown', handleStart);
+  node.addEventListener('touchstart', handleStart, { passive: true });
+  node.addEventListener('mouseup', handleEnd);
+  node.addEventListener('mouseleave', handleEnd);
+  node.addEventListener('touchend', handleEnd);
+  node.addEventListener('touchcancel', handleEnd);
+
+  return {
+    update(newOptions) {
+      duration = newOptions.duration ?? 500;
+      onLongPress = newOptions.onLongPress;
+    },
+    destroy() {
+      handleEnd();
+      node.removeEventListener('mousedown', handleStart);
+      node.removeEventListener('touchstart', handleStart);
+      node.removeEventListener('mouseup', handleEnd);
+      node.removeEventListener('mouseleave', handleEnd);
+      node.removeEventListener('touchend', handleEnd);
+      node.removeEventListener('touchcancel', handleEnd);
+    }
+  };
+}
+
+/**
+ * Escape Key Action
+ *
+ * Fires callback when Escape is pressed while element or children have focus.
+ *
+ * @param {HTMLElement} node
+ * @param {() => void} callback
+ *
+ * @example
+ * <dialog use:escapeKey={handleClose}>...</dialog>
+ */
+export function escapeKey(node, callback) {
+  let handler = callback;
+
+  function handleKeydown(event) {
+    if (event.key === 'Escape') {
+      event.preventDefault();
+      handler?.();
+    }
+  }
+
+  // Listen on document for global escape handling
+  document.addEventListener('keydown', handleKeydown);
+
+  return {
+    update(newCallback) {
+      handler = newCallback;
+    },
+    destroy() {
+      document.removeEventListener('keydown', handleKeydown);
+    }
+  };
+}
+
+/**
+ * Portal Action
+ *
+ * Moves element to a different location in the DOM.
+ * Useful for modals, toasts, tooltips.
+ *
+ * @param {HTMLElement} node
+ * @param {string | HTMLElement} [target] - CSS selector or element (default: document.body)
+ *
+ * @example
+ * <div use:portal>Portaled to body</div>
+ * <div use:portal="#modal-root">Portaled to #modal-root</div>
+ */
+export function portal(node, target = 'body') {
+  let targetEl;
+
+  function update(newTarget) {
+    targetEl = typeof newTarget === 'string'
+      ? document.querySelector(newTarget)
+      : newTarget;
+
+    if (targetEl) {
+      targetEl.appendChild(node);
+    }
+  }
+
+  update(target);
+
+  return {
+    update,
+    destroy() {
+      node.remove();
+    }
+  };
+}
+
+/**
+ * Intersection Observer Action
+ *
+ * Observes element visibility in viewport.
+ *
+ * @param {HTMLElement} node
+ * @param {{ onIntersect: (entry: IntersectionObserverEntry) => void, options?: IntersectionObserverInit }} config
+ *
+ * @example
+ * <div use:intersect={{ onIntersect: (e) => isVisible = e.isIntersecting }}>
+ *   Lazy loaded content
+ * </div>
+ */
+export function intersect(node, config) {
+  let { onIntersect, options = {} } = config;
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => onIntersect?.(entry));
+  }, options);
+
+  observer.observe(node);
+
+  return {
+    update(newConfig) {
+      onIntersect = newConfig.onIntersect;
+    },
+    destroy() {
+      observer.disconnect();
+    }
+  };
+}
+
+/**
+ * Resize Observer Action
+ *
+ * Observes element size changes.
+ *
+ * @param {HTMLElement} node
+ * @param {(entry: ResizeObserverEntry) => void} callback
+ *
+ * @example
+ * <div use:resize={(entry) => width = entry.contentRect.width}>
+ *   Responsive content
+ * </div>
+ */
+export function resize(node, callback) {
+  let handler = callback;
+
+  const observer = new ResizeObserver((entries) => {
+    entries.forEach(entry => handler?.(entry));
+  });
+
+  observer.observe(node);
+
+  return {
+    update(newCallback) {
+      handler = newCallback;
+    },
+    destroy() {
+      observer.disconnect();
+    }
+  };
+}
+
+/**
+ * Copy to Clipboard Action
+ *
+ * Copies element's text content or provided value on click.
+ *
+ * @param {HTMLElement} node
+ * @param {{ value?: string, onCopy?: () => void, onError?: (err: Error) => void }} [options]
+ *
+ * @example
+ * <button use:copy={{ value: 'Text to copy', onCopy: () => showToast('Copied!') }}>
+ *   Copy
+ * </button>
+ */
+export function copy(node, options = {}) {
+  let { value, onCopy, onError } = options;
+
+  async function handleClick() {
+    try {
+      const text = value ?? node.textContent ?? '';
+      await navigator.clipboard.writeText(text);
+      onCopy?.();
+    } catch (err) {
+      onError?.(err);
+    }
+  }
+
+  node.addEventListener('click', handleClick);
+
+  return {
+    update(newOptions) {
+      value = newOptions.value;
+      onCopy = newOptions.onCopy;
+      onError = newOptions.onError;
+    },
+    destroy() {
+      node.removeEventListener('click', handleClick);
+    }
+  };
+}

package/src/components/docs/CodeBlock.svelte

@@ -0,0 +1,203 @@
+<!--
+  @component CodeBlock
+
+  Syntax-highlighted code block with copy-to-clipboard functionality.
+  Uses Shiki for highlighting via CSS variables for theme compatibility.
+
+  @example
+  ```svelte
+  <CodeBlock
+    code={`const greeting = "Hello, World!";`}
+    lang="javascript"
+    filename="example.js"
+  />
+  ```
+-->
+<script>
+  import {getHighlighter} from '../../utils/highlighter.js';
+  import {Copy, Check} from '@lucide/svelte';
+
+  let {
+    /** The code to display */
+    code = '',
+    /** Language for syntax highlighting */
+    lang = 'javascript',
+    /** Optional filename to display in header */
+    filename = '',
+    /** Show line numbers */
+    showLineNumbers = false,
+    /** Additional CSS classes */
+    class: className = ''
+  } = $props();
+
+  let copied = $state(false);
+  let highlightedCode = $state('');
+
+  $effect(() => {
+    highlightCodeAsync();
+  });
+
+  async function highlightCodeAsync() {
+    try {
+      const highlighter = await getHighlighter();
+      highlightedCode = highlighter.codeToHtml(code.trim(), {
+        lang: lang || 'text',
+        theme: 'css-variables'
+      });
+    } catch (e) {
+      highlightedCode = `<pre><code>${escapeHtml(code)}</code></pre>`;
+    }
+  }
+
+  function escapeHtml(str) {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+
+  async function copyCode() {
+    try {
+      await navigator.clipboard.writeText(code.trim());
+      copied = true;
+      setTimeout(() => copied = false, 2000);
+    } catch (e) {
+      console.error('Failed to copy:', e);
+    }
+  }
+</script>
+
+<div class="jera-code-block {className}">
+  {#if filename}
+    <div class="code-header">
+      <span class="code-filename">{filename}</span>
+      <span class="code-lang">{lang}</span>
+    </div>
+  {/if}
+
+  <div class="code-container">
+    <button
+      class="copy-btn"
+      onclick={copyCode}
+      aria-label={copied ? 'Copied!' : 'Copy code'}
+    >
+      {#if copied}
+        <Check size={16} />
+      {:else}
+        <Copy size={16} />
+      {/if}
+    </button>
+
+    <div class="code-content" class:with-lines={showLineNumbers}>
+      {@html highlightedCode}
+    </div>
+  </div>
+</div>
+
+<style>
+  .jera-code-block {
+    position: relative;
+    border-radius: var(--radius-md, 0.5rem);
+    overflow: hidden;
+    background: var(--color-base1, var(--base1, #1a1f26));
+    border: 1px solid var(--color-border, var(--base2, #2d3748));
+  }
+
+  .code-header {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+    padding: 0.5rem 1rem;
+    background: var(--color-base0, var(--base0, #0f1419));
+    border-bottom: 1px solid var(--color-border, var(--base2, #2d3748));
+    font-size: 0.75rem;
+  }
+
+  .code-filename {
+    color: var(--color-base5, var(--base5, #e2e8f0));
+    font-family: var(--font-mono, monospace);
+  }
+
+  .code-lang {
+    color: var(--color-base4, var(--base4, #a0aec0));
+    text-transform: uppercase;
+    font-size: 0.625rem;
+    letter-spacing: 0.05em;
+  }
+
+  .code-container {
+    position: relative;
+  }
+
+  .copy-btn {
+    position: absolute;
+    top: 0.75rem;
+    right: 0.75rem;
+    z-index: 10;
+    padding: 0.5rem;
+    border: none;
+    border-radius: var(--radius-sm, 0.25rem);
+    background: var(--color-base2, var(--base2, #242a33));
+    color: var(--color-base4, var(--base4, #a0aec0));
+    cursor: pointer;
+    opacity: 0;
+    transition: opacity 0.15s, background 0.15s, color 0.15s;
+  }
+
+  .jera-code-block:hover .copy-btn {
+    opacity: 1;
+  }
+
+  .copy-btn:hover {
+    background: var(--color-base3, var(--base3, #4a5568));
+    color: var(--color-base6, var(--base6, #f7fafc));
+  }
+
+  .code-content {
+    overflow-x: auto;
+  }
+
+  .code-content :global(pre) {
+    margin: 0;
+    padding: 1rem;
+    background: transparent !important;
+    font-family: var(--font-mono, monospace);
+    font-size: 0.875rem;
+    line-height: 1.6;
+  }
+
+  .code-content :global(code) {
+    font-family: inherit;
+  }
+
+  /* Shiki CSS variables theme - compatible with both jera and selify themes */
+  .code-content {
+    --shiki-color-text: var(--color-base5, var(--base5, #e2e8f0));
+    --shiki-color-background: transparent;
+    --shiki-token-constant: var(--blue, #83d2fc);
+    --shiki-token-string: var(--green, #6dd672);
+    --shiki-token-comment: var(--base3, #565e78);
+    --shiki-token-keyword: var(--magenta, #c974e6);
+    --shiki-token-parameter: var(--peach, #ff9982);
+    --shiki-token-function: var(--blue, #83d2fc);
+    --shiki-token-string-expression: var(--green, #6dd672);
+    --shiki-token-punctuation: var(--color-base4, var(--base4, #a0aec0));
+    --shiki-token-link: var(--blue, #83d2fc);
+  }
+
+  /* Line numbers */
+  .with-lines :global(pre) {
+    counter-reset: line;
+  }
+
+  .with-lines :global(.line::before) {
+    counter-increment: line;
+    content: counter(line);
+    display: inline-block;
+    width: 2rem;
+    margin-right: 1rem;
+    text-align: right;
+    color: var(--color-base3, var(--base3, #4a5568));
+    user-select: none;
+  }
+</style>

package/src/components/docs/DocSection.svelte

@@ -0,0 +1,120 @@
+<!--
+  @component DocSection
+
+  A documentation section with optional anchor link, title, description,
+  and content area. Useful for organizing documentation into scannable sections.
+
+  @example
+  ```svelte
+  <DocSection id="installation" title="Installation" description="How to install the package">
+    <CodeBlock code="npm install @miozu/jera" lang="bash" />
+  </DocSection>
+  ```
+-->
+<script>
+  import {Link2} from '@lucide/svelte';
+
+  let {
+    /** Unique ID for anchor links */
+    id = '',
+    /** Section title */
+    title = '',
+    /** Optional description below title */
+    description = '',
+    /** Heading level (2-6) */
+    level = 2,
+    /** Show anchor link on hover */
+    showAnchor = true,
+    /** Children content */
+    children,
+    /** Additional CSS classes */
+    class: className = ''
+  } = $props();
+
+  const Tag = `h${level}`;
+</script>
+
+<section class="jera-doc-section {className}" {id}>
+  {#if title}
+    <div class="section-header">
+      <svelte:element this={Tag} class="section-title">
+        {title}
+        {#if showAnchor && id}
+          <a href="#{id}" class="anchor-link" aria-label="Link to {title}">
+            <Link2 size={16} />
+          </a>
+        {/if}
+      </svelte:element>
+      {#if description}
+        <p class="section-description">{description}</p>
+      {/if}
+    </div>
+  {/if}
+
+  <div class="section-content">
+    {@render children?.()}
+  </div>
+</section>
+
+<style>
+  .jera-doc-section {
+    margin-bottom: 2rem;
+    scroll-margin-top: 2rem;
+  }
+
+  .section-header {
+    margin-bottom: 1rem;
+  }
+
+  .section-title {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    margin: 0 0 0.5rem 0;
+    font-weight: 600;
+    color: var(--color-base6, var(--base6, #f3f4f7));
+  }
+
+  h2.section-title {
+    font-size: 1.5rem;
+    padding-bottom: 0.5rem;
+    border-bottom: 1px solid var(--color-border, var(--base2, #2d3748));
+  }
+
+  h3.section-title {
+    font-size: 1.25rem;
+  }
+
+  h4.section-title {
+    font-size: 1.125rem;
+  }
+
+  h5.section-title,
+  h6.section-title {
+    font-size: 1rem;
+  }
+
+  .anchor-link {
+    opacity: 0;
+    color: var(--color-base4, var(--base4, #a0aec0));
+    transition: opacity 0.15s, color 0.15s;
+  }
+
+  .section-title:hover .anchor-link {
+    opacity: 1;
+  }
+
+  .anchor-link:hover {
+    color: var(--color-primary, var(--magenta, #c974e6));
+  }
+
+  .section-description {
+    margin: 0;
+    color: var(--color-base4, var(--base4, #a0aec0));
+    line-height: 1.6;
+  }
+
+  .section-content {
+    /* Content inherits full width */
+  }
+</style>