@miozu/jera 0.3.0 → 0.4.3

package/src/components/docs/CodeBlock.svelte

@@ -0,0 +1,204 @@
+<!--
+  @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';
+
+  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 icon (inline SVG - no external dependency) -->
+        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20 6 9 17l-5-5"/></svg>
+      {:else}
+        <!-- Copy icon (inline SVG - no external dependency) -->
+        <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>
+      {/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>

package/src/components/docs/PropsTable.svelte

@@ -0,0 +1,136 @@
+<!--
+  @component PropsTable
+
+  Display component/function props in a clean, readable table.
+  Commonly used for API documentation.
+
+  @example
+  ```svelte
+  <PropsTable props={[
+    { name: 'variant', type: 'string', default: '"default"', description: 'Visual style' },
+    { name: 'disabled', type: 'boolean', default: 'false', description: 'Disable interactions' },
+    { name: 'onclick', type: 'function', required: true, description: 'Click handler' }
+  ]} />
+  ```
+-->
+<script>
+  /**
+   * @typedef {Object} PropDef
+   * @property {string} name - Property name
+   * @property {string} type - Type annotation
+   * @property {string} [default] - Default value
+   * @property {string} description - Description
+   * @property {boolean} [required] - Whether prop is required
+   */
+
+  /** @type {{ props: PropDef[], class?: string }} */
+  let {
+    props = [],
+    class: className = ''
+  } = $props();
+</script>
+
+<div class="jera-props-table {className}">
+  <table>
+    <thead>
+      <tr>
+        <th>Prop</th>
+        <th>Type</th>
+        <th>Default</th>
+        <th>Description</th>
+      </tr>
+    </thead>
+    <tbody>
+      {#each props as prop}
+        <tr>
+          <td class="prop-name">
+            <code>{prop.name}</code>
+            {#if prop.required}
+              <span class="required" title="Required">*</span>
+            {/if}
+          </td>
+          <td class="prop-type">
+            <code>{prop.type}</code>
+          </td>
+          <td class="prop-default">
+            {#if prop.default !== undefined}
+              <code>{prop.default}</code>
+            {:else}
+              <span class="muted">-</span>
+            {/if}
+          </td>
+          <td class="prop-desc">{prop.description}</td>
+        </tr>
+      {/each}
+    </tbody>
+  </table>
+</div>
+
+<style>
+  .jera-props-table {
+    overflow-x: auto;
+    border: 1px solid var(--color-border, var(--base2, #2d3748));
+    border-radius: var(--radius-md, 0.5rem);
+  }
+
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.875rem;
+  }
+
+  th {
+    text-align: left;
+    padding: 0.75rem 1rem;
+    background: var(--color-base1, var(--base1, #1a1f26));
+    border-bottom: 1px solid var(--color-border, var(--base2, #2d3748));
+    font-weight: 500;
+    color: var(--color-base5, var(--base5, #e2e8f0));
+    white-space: nowrap;
+  }
+
+  td {
+    padding: 0.75rem 1rem;
+    border-bottom: 1px solid var(--color-border, var(--base2, #2d3748));
+    vertical-align: top;
+  }
+
+  tr:last-child td {
+    border-bottom: none;
+  }
+
+  .prop-name code {
+    font-family: var(--font-mono, monospace);
+    font-weight: 500;
+    color: var(--color-primary, var(--magenta, #c974e6));
+  }
+
+  .required {
+    color: var(--color-error, var(--red, #eb3137));
+    margin-left: 0.25rem;
+  }
+
+  .prop-type code {
+    font-family: var(--font-mono, monospace);
+    font-size: 0.8125rem;
+    color: var(--color-base4, var(--base4, #a0aec0));
+    background: var(--color-base1, var(--base1, #1a1f26));
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+  }
+
+  .prop-default code {
+    font-family: var(--font-mono, monospace);
+    font-size: 0.8125rem;
+    color: var(--color-success, var(--green, #6dd672));
+  }
+
+  .muted {
+    color: var(--color-base3, var(--base3, #4a5568));
+  }
+
+  .prop-desc {
+    color: var(--color-base4, var(--base4, #a0aec0));
+    line-height: 1.5;
+  }
+</style>

package/src/components/docs/SplitPane.svelte

@@ -0,0 +1,98 @@
+<!--
+  @component SplitPane
+
+  Two-pane layout component for documentation with description on the left
+  and code/examples on the right. Responsive - stacks vertically on mobile.
+
+  @example
+  ```svelte
+  <SplitPane>
+    {#snippet left()}
+      <h2>Function Description</h2>
+      <p>This function does something amazing...</p>
+    {/snippet}
+    {#snippet right()}
+      <CodeBlock code={exampleCode} lang="javascript" />
+    {/snippet}
+  </SplitPane>
+  ```
+-->
+<script>
+  let {
+    /** Left pane content (description, prose) */
+    left,
+    /** Right pane content (code, examples) */
+    right,
+    /** Ratio of left:right pane widths (e.g., '1:1', '2:1', '3:2') */
+    ratio = '1:1',
+    /** Gap between panes */
+    gap = '2rem',
+    /** Minimum height */
+    minHeight = 'auto',
+    /** Whether both panes should independently scroll */
+    stickyRight = false,
+    /** Additional CSS classes */
+    class: className = ''
+  } = $props();
+
+  // Parse ratio into flex values
+  const [leftFlex, rightFlex] = $derived.by(() => {
+    const parts = ratio.split(':').map(Number);
+    return [parts[0] || 1, parts[1] || 1];
+  });
+</script>
+
+<div
+  class="jera-split-pane {className}"
+  class:sticky-right={stickyRight}
+  style:--gap={gap}
+  style:--left-flex={leftFlex}
+  style:--right-flex={rightFlex}
+  style:--min-height={minHeight}
+>
+  <div class="pane pane-left">
+    {@render left?.()}
+  </div>
+  <div class="pane pane-right">
+    {@render right?.()}
+  </div>
+</div>
+
+<style>
+  .jera-split-pane {
+    display: flex;
+    flex-direction: column;
+    gap: var(--gap);
+    min-height: var(--min-height);
+    width: 100%;
+  }
+
+  @media (min-width: 1024px) {
+    .jera-split-pane {
+      flex-direction: row;
+    }
+  }
+
+  .pane {
+    min-width: 0;
+  }
+
+  .pane-left {
+    flex: var(--left-flex);
+  }
+
+  .pane-right {
+    flex: var(--right-flex);
+  }
+
+  /* Sticky right pane for scrollable docs */
+  @media (min-width: 1024px) {
+    .sticky-right .pane-right {
+      position: sticky;
+      top: 1rem;
+      align-self: flex-start;
+      max-height: calc(100vh - 2rem);
+      overflow-y: auto;
+    }
+  }
+</style>

package/src/components/docs/index.js

@@ -0,0 +1,14 @@
+/**
+ * Documentation components for @miozu/jera
+ *
+ * Components for building documentation sites with syntax highlighting,
+ * split-pane layouts, and structured content sections.
+ *
+ * @example
+ * import { CodeBlock, PropsTable, SplitPane, DocSection } from '@miozu/jera';
+ */
+
+export { default as CodeBlock } from './CodeBlock.svelte';
+export { default as PropsTable } from './PropsTable.svelte';
+export { default as SplitPane } from './SplitPane.svelte';
+export { default as DocSection } from './DocSection.svelte';