@hypermedia-components/core 0.1.2 → 0.1.3

package/dist/code-editor.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Install the editable-code behavior on the given root.
+ *
+ * Enhances every `.hc-code[data-editable]` once and re-scans subtrees
+ * delivered by htmx (`htmx:load`). Repeated calls on the same root return the
+ * same uninstaller.
+ *
+ * @param {Document|Element} [root=document]
+ *   The scope to scan. Defaults to the global document when available.
+ * @returns {() => void} an idempotent uninstaller that removes the synced
+ *   gutters and listeners it added.
+ */
+export function installCodeEditor(root?: Document | Element): () => void;

package/dist/code-editor.js

@@ -0,0 +1,121 @@
+// installCodeEditor — upgrade an editable `hc-code` field with a synced
+// line-number gutter (issue #255).
+//
+//   <div class="hc-code" data-editable data-gutter="line-numbers">
+//     <textarea class="hc-code__input" name="content" spellcheck="false">SELECT 1</textarea>
+//   </div>
+//
+// The value lives in a real <textarea name>, so it submits in forms, works
+// with htmx (hx-post / hx-include / hx-vals), and degrades to a plain
+// monospace textarea when this script is absent. When `data-gutter="line-numbers"`
+// is set, the behavior inserts a `.hc-code__gutter` element before the
+// textarea and keeps it in sync: it re-numbers on input and matches the
+// textarea's vertical scroll. To keep the numbers aligned with the lines it
+// sets the textarea to not soft-wrap (`wrap="off"`), so long lines scroll
+// horizontally rather than pushing the numbers out of step.
+//
+// Syntax highlighting is out of scope (a CSP-safe overlay is a possible
+// follow-up). installCodeEditor(root = document) is idempotent and returns an
+// uninstaller; fields swapped in by htmx are enhanced on `htmx:load`.
+
+const INSTALL_KEY = '__hcCodeEditorUninstall';
+
+function lineNumbers(count) {
+  let out = '1';
+  for (let i = 2; i <= count; i += 1) out += '\n' + i;
+  return out;
+}
+
+function enhance(container) {
+  const textarea = container.querySelector('.hc-code__input');
+  if (!textarea) return null;
+  if (container.dataset.gutter !== 'line-numbers') return () => {};
+  if (container.querySelector('.hc-code__gutter')) return () => {};
+
+  // Keep line numbers aligned: a soft-wrapped line would span several rows
+  // while the gutter counts one. Horizontal scroll instead.
+  const prevWrap = textarea.getAttribute('wrap');
+  textarea.setAttribute('wrap', 'off');
+
+  const gutter = container.ownerDocument.createElement('div');
+  gutter.className = 'hc-code__gutter';
+  gutter.setAttribute('aria-hidden', 'true');
+  container.insertBefore(gutter, textarea);
+
+  let lastCount = 0;
+  const renumber = () => {
+    const count = Math.max(1, textarea.value.split('\n').length);
+    if (count !== lastCount) {
+      gutter.textContent = lineNumbers(count);
+      lastCount = count;
+    }
+  };
+  const syncScroll = () => {
+    gutter.scrollTop = textarea.scrollTop;
+  };
+  const onInput = () => {
+    renumber();
+    syncScroll();
+  };
+
+  textarea.addEventListener('input', onInput);
+  textarea.addEventListener('scroll', syncScroll);
+  renumber();
+  syncScroll();
+
+  return () => {
+    textarea.removeEventListener('input', onInput);
+    textarea.removeEventListener('scroll', syncScroll);
+    gutter.remove();
+    if (prevWrap == null) textarea.removeAttribute('wrap');
+    else textarea.setAttribute('wrap', prevWrap);
+  };
+}
+
+/**
+ * Install the editable-code behavior on the given root.
+ *
+ * Enhances every `.hc-code[data-editable]` once and re-scans subtrees
+ * delivered by htmx (`htmx:load`). Repeated calls on the same root return the
+ * same uninstaller.
+ *
+ * @param {Document|Element} [root=document]
+ *   The scope to scan. Defaults to the global document when available.
+ * @returns {() => void} an idempotent uninstaller that removes the synced
+ *   gutters and listeners it added.
+ */
+export function installCodeEditor(root = (typeof document !== 'undefined' ? document : null)) {
+  if (!root) return () => {};
+  if (root[INSTALL_KEY]) return root[INSTALL_KEY];
+
+  const enhanced = new WeakSet();
+  const detachers = [];
+
+  const scan = (scope) => {
+    if (!scope || !scope.querySelectorAll) return;
+    scope.querySelectorAll('.hc-code[data-editable]').forEach((el) => {
+      if (enhanced.has(el)) return;
+      const detach = enhance(el);
+      if (detach) {
+        enhanced.add(el);
+        detachers.push(detach);
+      }
+    });
+  };
+
+  scan(root);
+
+  const target = root.body || root;
+  const onLoad = (event) => scan(event && event.target);
+  target.addEventListener('htmx:load', onLoad);
+
+  const uninstall = () => {
+    if (root[INSTALL_KEY] !== uninstall) return;
+    target.removeEventListener('htmx:load', onLoad);
+    detachers.forEach((fn) => fn());
+    detachers.length = 0;
+    delete root[INSTALL_KEY];
+  };
+  root[INSTALL_KEY] = uninstall;
+  return uninstall;
+}

package/dist/hc-code.css

@@ -0,0 +1,275 @@
+/* hc-code — code surface (issues #253, #256, #255).
+ *
+ * A monospace surface styled from the kit's tokens. The read-only modes
+ * need no script (CSP `default-src 'self'` safe); the editable mode is a
+ * real <textarea> that `installCodeEditor()` upgrades with a synced
+ * line-number gutter. Syntax highlighting is out of scope — the lines are
+ * plain text (a server-tokenized or behavior-driven follow-up may add it
+ * additively later).
+ *
+ * 1. Plain block — apply to a <pre>:
+ *
+ *      <pre class="hc-code"><code>SELECT 1
+ *      FROM t</code></pre>
+ *
+ *    Overflow is a horizontal scroll by default; `data-wrap="on"` soft-wraps
+ *    long lines instead.
+ *
+ * 2. Line-numbered / decorable — apply to an <ol>, one <li class="hc-code__line">
+ *    per line, with `data-gutter="line-numbers"`:
+ *
+ *      <ol class="hc-code" data-gutter="line-numbers">
+ *        <li class="hc-code__line">SELECT *</li>
+ *        <li class="hc-code__line" data-state="covered">  FROM orders</li>
+ *        <li class="hc-code__line" data-state="missed"> WHERE total &gt; 0</li>
+ *      </ol>
+ *
+ * 3. Unified diff — apply `data-mode="diff"` to the <ol>; each line carries a
+ *    `data-state` of added | removed | context and `data-old` / `data-new`
+ *    line numbers (the server computes the hunks — the kit only styles them):
+ *
+ *      <ol class="hc-code" data-mode="diff">
+ *        <li class="hc-code__line" data-state="context" data-old="12" data-new="12">  SELECT id</li>
+ *        <li class="hc-code__line" data-state="removed" data-old="13">  FROM users</li>
+ *        <li class="hc-code__line" data-state="added"   data-new="13">  FROM app_users</li>
+ *      </ol>
+ *
+ * 4. Editable — a <div class="hc-code" data-editable> wrapping a real
+ *    <textarea class="hc-code__input" name="…">. The value submits in forms
+ *    and with htmx; without JS it is a plain monospace textarea.
+ *    `installCodeEditor()` adds a synced line-number gutter when
+ *    `data-gutter="line-numbers"` is set:
+ *
+ *      <div class="hc-code" data-editable data-gutter="line-numbers">
+ *        <textarea class="hc-code__input" name="content" spellcheck="false">SELECT 1</textarea>
+ *      </div>
+ *
+ * Per-line `data-state` colours from semantic status tokens, so the same
+ * markup themes correctly in light and dark:
+ *   added / covered  → success    removed / missed → error    context → muted
+ *
+ * Legend: `.hc-code__swatch[data-state]` is a small colour chip the consumer
+ * composes into a legend next to a coverage block.
+ *
+ * Accessibility: a horizontally scrollable block must be keyboard-reachable,
+ * so make it a focusable, labelled region — `tabindex="0"` plus
+ * `role="region"` and an `aria-label`. Colour is never the only diff cue: the
+ * unified-diff gutter prints a `+` / `-` sign glyph alongside the tint.
+ */
+@layer hc.components {
+  .hc-code {
+    margin: 0;
+    border: 1px solid var(--hc-code-border);
+    border-radius: var(--hc-code-radius);
+    background: var(--hc-code-bg);
+    color: var(--hc-code-fg);
+    font-family: var(--hc-code-font-family);
+    font-size: var(--hc-code-font-size);
+    line-height: var(--hc-code-line-height);
+    overflow-x: auto;
+    tab-size: 2;
+  }
+
+  /* Plain block on a <pre>. */
+  .hc-code:where(pre) {
+    padding: var(--hc-code-padding-block) var(--hc-code-padding-inline);
+    white-space: pre;
+  }
+
+  .hc-code:where(pre)[data-wrap="on"] {
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+  }
+
+  /* Line-based modes on an <ol>: reset the list, keep the inline padding on
+   * the lines so a line's background tint spans the full block width. */
+  .hc-code:where(ol) {
+    padding-block: var(--hc-code-padding-block);
+    padding-inline: 0;
+    list-style: none;
+    counter-reset: hc-code-line;
+  }
+
+  .hc-code__line {
+    padding-inline: var(--hc-code-padding-inline);
+    white-space: pre;
+  }
+
+  .hc-code[data-wrap="on"] .hc-code__line {
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+  }
+
+  /* --- Line-number gutter ------------------------------------------------ */
+
+  .hc-code[data-gutter="line-numbers"] .hc-code__line {
+    position: relative;
+    counter-increment: hc-code-line;
+    padding-inline-start: var(--hc-code-gutter-width);
+  }
+
+  .hc-code[data-gutter="line-numbers"] .hc-code__line::before {
+    content: counter(hc-code-line);
+    position: absolute;
+    inset-inline-start: 0;
+    inline-size: calc(var(--hc-code-gutter-width) - var(--hc-code-gutter-gap));
+    color: var(--hc-code-gutter-fg);
+    text-align: end;
+    user-select: none;
+  }
+
+  /* --- Unified diff ------------------------------------------------------ */
+
+  .hc-code[data-mode="diff"] .hc-code__line {
+    position: relative;
+
+    /* Reserve two right-aligned number columns; the sign + code follow. */
+    padding-inline-start: calc(var(--hc-code-num-width) * 2 + var(--hc-code-gutter-gap));
+    list-style-position: inside;
+  }
+
+  .hc-code[data-mode="diff"] .hc-code__line::before {
+    content: attr(data-old);
+    position: absolute;
+    inset-inline-start: 0;
+    inline-size: var(--hc-code-num-width);
+    color: var(--hc-code-gutter-fg);
+    text-align: end;
+    user-select: none;
+  }
+
+  .hc-code[data-mode="diff"] .hc-code__line::after {
+    content: attr(data-new);
+    position: absolute;
+    inset-inline-start: var(--hc-code-num-width);
+    inline-size: var(--hc-code-num-width);
+    color: var(--hc-code-gutter-fg);
+    text-align: end;
+    user-select: none;
+  }
+
+  /* The +/- sign rides the list marker, so it is never selected when the
+   * code text is copied. A neutral two-space marker keeps context lines and
+   * the code column aligned. */
+  .hc-code[data-mode="diff"] .hc-code__line::marker {
+    content: "  ";
+    color: var(--hc-code-gutter-fg);
+  }
+
+  .hc-code[data-mode="diff"] .hc-code__line[data-state="added"]::marker {
+    content: "+ ";
+    color: var(--hc-code-added-marker);
+  }
+
+  .hc-code[data-mode="diff"] .hc-code__line[data-state="removed"]::marker {
+    content: "- ";
+    color: var(--hc-code-removed-marker);
+  }
+
+  /* --- Per-line state (shared by gutter + diff modes) -------------------- */
+
+  .hc-code__line[data-state="added"],
+  .hc-code__line[data-state="covered"] {
+    background: var(--hc-code-added-bg);
+    box-shadow: inset 0.1875rem 0 0 var(--hc-code-added-marker);
+  }
+
+  .hc-code__line[data-state="removed"],
+  .hc-code__line[data-state="missed"] {
+    background: var(--hc-code-removed-bg);
+    box-shadow: inset 0.1875rem 0 0 var(--hc-code-removed-marker);
+  }
+
+  .hc-code__line[data-state="context"] {
+    color: var(--hc-code-context-fg);
+  }
+
+  /* --- Legend swatch ----------------------------------------------------- */
+
+  .hc-code__swatch {
+    display: inline-block;
+    inline-size: 0.75em;
+    block-size: 0.75em;
+    border: 1px solid var(--hc-code-border);
+    border-radius: 2px;
+    vertical-align: middle;
+  }
+
+  .hc-code__swatch[data-state="added"],
+  .hc-code__swatch[data-state="covered"] {
+    background: var(--hc-code-added-bg);
+    border-color: var(--hc-code-added-marker);
+  }
+
+  .hc-code__swatch[data-state="removed"],
+  .hc-code__swatch[data-state="missed"] {
+    background: var(--hc-code-removed-bg);
+    border-color: var(--hc-code-removed-marker);
+  }
+
+  /* --- Editable field (#255) --------------------------------------------- */
+
+  /* A real <textarea> on the same surface. The textarea drives the height;
+   * installCodeEditor() overlays the line-number gutter as an absolutely
+   * positioned column so it tracks the textarea's visible box (not its own
+   * content height) and scrolls in sync. Without JS it is just the textarea,
+   * full width. */
+  .hc-code[data-editable] {
+    position: relative;
+    display: block;
+    padding: 0;
+    overflow: hidden;
+  }
+
+  .hc-code[data-editable]:focus-within {
+    border-color: var(--hc-code-focus-border);
+    box-shadow: inset 0 0 0 1px var(--hc-code-focus-border);
+  }
+
+  /* The synced line-number gutter (created by the behavior, decorative).
+   * inset-block:0 ties its height to the textarea's visible box; overflow is
+   * hidden and the behavior matches its scrollTop to the textarea. */
+  .hc-code__gutter {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    inline-size: var(--hc-code-gutter-width);
+    box-sizing: border-box;
+    padding-block: var(--hc-code-padding-block);
+    padding-inline-end: var(--hc-code-gutter-gap);
+    overflow: hidden;
+    color: var(--hc-code-gutter-fg);
+    text-align: end;
+    white-space: pre;
+    pointer-events: none;
+    user-select: none;
+  }
+
+  .hc-code__input {
+    display: block;
+    box-sizing: border-box;
+    inline-size: 100%;
+    min-block-size: var(--hc-code-input-min-height);
+    margin: 0;
+    padding-block: var(--hc-code-padding-block);
+    padding-inline: var(--hc-code-padding-inline);
+    border: 0;
+    background: transparent;
+    color: inherit;
+    font-family: inherit;
+    font-size: inherit;
+    line-height: inherit;
+    resize: vertical;
+    tab-size: inherit;
+  }
+
+  /* Make room for the gutter overlay. */
+  .hc-code[data-editable][data-gutter="line-numbers"] .hc-code__input {
+    padding-inline-start: var(--hc-code-gutter-width);
+  }
+
+  /* The container shows the :focus-within ring instead. */
+  .hc-code__input:focus {
+    outline: none;
+  }
+}

package/dist/hc-sparkline.css

@@ -0,0 +1,62 @@
+/* hc-sparkline — a tiny inline trend chart (issue #254).
+ *
+ * A word-sized line (optionally filled) for showing a metric's recent
+ * direction next to the number, e.g. a coverage or pass-rate trend. It is
+ * CSP-safe (`default-src 'self'`): there is no charting dependency and no
+ * inline script — `installSparkline()` draws the SVG from `data-values` with
+ * the DOM API, and a server may emit the same SVG directly.
+ *
+ *   <span class="hc-sparkline" data-values="0.7,0.74,0.8,0.78,0.82"
+ *         aria-label="SQL line coverage trend"></span>
+ *
+ * The stroke and fill use `currentColor`, so a single `color` declaration
+ * themes the whole mark; `data-variant` swaps it for a success / warning /
+ * error trend colour. Size comes from `--hc-sparkline-width` / `-height`
+ * (or set the host's inline-size / block-size directly).
+ */
+@layer hc.components {
+  .hc-sparkline {
+    display: inline-block;
+    inline-size: var(--hc-sparkline-width);
+    block-size: var(--hc-sparkline-height);
+    color: var(--hc-sparkline-color);
+    vertical-align: middle;
+  }
+
+  .hc-sparkline__svg {
+    display: block;
+    inline-size: 100%;
+    block-size: 100%;
+    overflow: visible;
+  }
+
+  .hc-sparkline__line {
+    fill: none;
+    stroke: currentColor;
+    stroke-width: var(--hc-sparkline-stroke-width);
+    stroke-linecap: round;
+    stroke-linejoin: round;
+
+    /* Keep the stroke crisp regardless of how the viewBox stretches to the
+     * host's aspect ratio (preserveAspectRatio="none"). */
+    vector-effect: non-scaling-stroke;
+  }
+
+  .hc-sparkline__area {
+    fill: currentColor;
+    opacity: var(--hc-sparkline-area-opacity);
+    stroke: none;
+  }
+
+  .hc-sparkline[data-variant="success"] {
+    color: var(--hc-sparkline-success);
+  }
+
+  .hc-sparkline[data-variant="warning"] {
+    color: var(--hc-sparkline-warning);
+  }
+
+  .hc-sparkline[data-variant="error"] {
+    color: var(--hc-sparkline-error);
+  }
+}

package/dist/hc.behaviors.d.ts

@@ -30,5 +30,7 @@ import { installValidation } from './validation.js';
 import { installThemeToggle } from './theme-toggle.js';
 import { installFieldErrors } from './field-errors.js';
 import { installCsrfHeader } from './csrf-header.js';
-export { installConfirm, installToast, installCloseDialog, installClosePopover, installRemoteDialog, installTabs, installMenu, installMenubar, installNavmenu, installTooltip, installPopover, installSlider, installCombobox, installMulticombobox, installDrawer, installHovercard, installToggleGroup, installCarousel, installToolbar, installAvatar, installPasswordToggle, installContextMenu, installCommand, installCalendar, installInputOtp, installSplitter, installShell, installDatagrid, installValidation, installThemeToggle, installFieldErrors, installCsrfHeader };
+import { installSparkline } from './sparkline.js';
+import { installCodeEditor } from './code-editor.js';
+export { installConfirm, installToast, installCloseDialog, installClosePopover, installRemoteDialog, installTabs, installMenu, installMenubar, installNavmenu, installTooltip, installPopover, installSlider, installCombobox, installMulticombobox, installDrawer, installHovercard, installToggleGroup, installCarousel, installToolbar, installAvatar, installPasswordToggle, installContextMenu, installCommand, installCalendar, installInputOtp, installSplitter, installShell, installDatagrid, installValidation, installThemeToggle, installFieldErrors, installCsrfHeader, installSparkline, installCodeEditor };
 export { setMessages, resetMessages, getMessages, hasMessage, DEFAULT_MESSAGES } from "./i18n.js";

package/dist/hc.behaviors.js

@@ -39,6 +39,8 @@ import { installValidation } from './validation.js';
 import { installThemeToggle } from './theme-toggle.js';
 import { installFieldErrors } from './field-errors.js';
 import { installCsrfHeader } from './csrf-header.js';
+import { installSparkline } from './sparkline.js';
+import { installCodeEditor } from './code-editor.js';
 
 function init() {
   installConfirm();
@@ -73,6 +75,8 @@ function init() {
   installThemeToggle();
   installFieldErrors();
   installCsrfHeader();
+  installSparkline();
+  installCodeEditor();
 }
 
 if (typeof document !== 'undefined') {
@@ -116,6 +120,8 @@ export {
   installThemeToggle,
   installFieldErrors,
   installCsrfHeader,
+  installSparkline,
+  installCodeEditor,
 };
 
 // i18n — set the locale before this module's auto-init runs (e.g. inline