@joewinke/jatui 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joewinke/jatui",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "private": false,
   "description": "Shared Svelte 5 component library for JAT projects",
   "type": "module",

package/src/lib/actions/collapse.ts

@@ -0,0 +1,134 @@
+/**
+ * Tall-content collapse — Svelte action.
+ *
+ * Caps an arbitrarily-tall block at a max height with a fade-out gradient so it
+ * shows a preview instead of overflowing its container. The consumer renders the
+ * "Show more / Show less" toggle and owns the `expanded` boolean; the action does
+ * the measuring and applies the collapse styling.
+ *
+ * Why an action (not a wrapper-only component): most adoption sites are existing
+ * elements (`<p>`, a `prose` div, a `<ul>`, a `<pre>`), and an action attaches
+ * with zero DOM restructuring. A batteries-included `<Collapse>` wrapper that
+ * uses this action is also provided for greenfield use.
+ *
+ * ─── Why inline styles, not a CSS class ───────────────────────────────────────
+ *
+ * The action writes `max-height` / `overflow` / `mask-image` directly on the node
+ * when collapsed. That means it needs NO accompanying stylesheet — it works
+ * identically in Tailwind-utility components and scoped-CSS components, and
+ * consumers don't have to copy a `.collapse-*` rule into their app.css (the same
+ * trap rail.css has). Expanding clears the inline styles.
+ *
+ * ─── Why ResizeObserver, not a one-shot rAF ───────────────────────────────────
+ *
+ * Streaming chat answers and `{@html}` markdown bodies grow AFTER mount. A
+ * one-shot measurement on mount would miss them (and would wrongly hide the
+ * toggle on content that hasn't streamed in yet). A ResizeObserver re-measures
+ * whenever the content's natural height changes, so `collapsible` stays correct.
+ *
+ * `scrollHeight` reports the FULL content height even while `max-height` +
+ * `overflow:hidden` are applied, so the action can keep measuring without ever
+ * having to un-collapse first.
+ *
+ * ─── Usage — action form (most sites) ─────────────────────────────────────────
+ *
+ *   <script>
+ *     import { collapse } from 'jatui'
+ *     let collapsible = $state(false)
+ *     let expanded = $state(false)
+ *   </script>
+ *
+ *   <div use:collapse={{ expanded, onCollapsible: (c) => (collapsible = c) }}>
+ *     {content}
+ *   </div>
+ *   {#if collapsible}
+ *     <button onclick={() => (expanded = !expanded)}>
+ *       {expanded ? 'Show less ↑' : 'Show more ↓'}
+ *     </button>
+ *   {/if}
+ *
+ * For mapped lists, give each row its own `expanded` / `collapsible` state
+ * (e.g. a `SvelteSet` of ids) — one action instance attaches per row element.
+ */
+
+export interface CollapseOptions {
+	/** Max collapsed height in px. Content taller than this collapses. Default 120. */
+	threshold?: number;
+	/** Controlled expand state. When true, the node is never collapsed. Default false. */
+	expanded?: boolean;
+	/** Where the fade-to-transparent begins, as a %. Default 55. */
+	fadeStart?: number;
+	/** Slack (px) added to the threshold so a near-fit doesn't toggle. Default 4. */
+	epsilon?: number;
+	/**
+	 * Called whenever collapsibility changes (content crosses the threshold).
+	 * Drive the toggle button's visibility from this — it self-hides when the
+	 * content is shorter than the threshold.
+	 */
+	onCollapsible?: (collapsible: boolean) => void;
+}
+
+const DEFAULTS = { threshold: 120, expanded: false, fadeStart: 55, epsilon: 4 } as const;
+
+export function collapse(node: HTMLElement, options: CollapseOptions = {}) {
+	let opts = { ...DEFAULTS, ...options };
+	let collapsible = false;
+	let rafId = 0;
+	let applied = false;
+
+	function gradient() {
+		return `linear-gradient(to bottom, black ${opts.fadeStart}%, transparent 100%)`;
+	}
+
+	function apply() {
+		const shouldCollapse = collapsible && !opts.expanded;
+		if (shouldCollapse === applied) return; // idempotent — avoids RO feedback loops
+		applied = shouldCollapse;
+		if (shouldCollapse) {
+			node.style.maxHeight = `${opts.threshold}px`;
+			node.style.overflow = 'hidden';
+			node.style.maskImage = gradient();
+			node.style.webkitMaskImage = gradient();
+		} else {
+			node.style.maxHeight = '';
+			node.style.overflow = '';
+			node.style.maskImage = '';
+			node.style.webkitMaskImage = '';
+		}
+	}
+
+	function measure() {
+		// scrollHeight is the full content height even while collapsed.
+		const next = node.scrollHeight > opts.threshold + opts.epsilon;
+		if (next !== collapsible) {
+			collapsible = next;
+			opts.onCollapsible?.(collapsible);
+		}
+		apply();
+	}
+
+	function scheduleMeasure() {
+		cancelAnimationFrame(rafId);
+		rafId = requestAnimationFrame(measure);
+	}
+
+	// Re-measure when the content's natural size changes (streaming, {@html}, lazy images).
+	const ro = new ResizeObserver(scheduleMeasure);
+	ro.observe(node);
+
+	scheduleMeasure();
+
+	return {
+		update(next: CollapseOptions = {}) {
+			opts = { ...DEFAULTS, ...next };
+			// expanded/threshold/fade may have changed — re-apply (and re-measure
+			// in case threshold moved across the content height).
+			applied = !applied; // force apply() to re-evaluate against new opts
+			scheduleMeasure();
+		},
+		destroy() {
+			cancelAnimationFrame(rafId);
+			ro.disconnect();
+		},
+	};
+}

package/src/lib/components/ChipInput.svelte

@@ -1,15 +1,7 @@
-<script lang="ts">
-	/**
-	 * ChipInput - Generic contenteditable input with inline chips and autocomplete.
-	 *
-	 * Handles:
-	 * - Contenteditable div with placeholder
-	 * - Chip insertion/deletion (non-editable inline spans)
-	 * - Autocomplete dropdown with keyboard navigation
-	 * - Serialization (DOM -> text with chip markers)
-	 */
-
-	// --- Types ---
+<script module lang="ts">
+	// Public types — declared in the module script so that
+	// `import type { ChipSuggestion, SuggestionGroup, ChipInfo } from './ChipInput.svelte'`
+	// resolves. Types exported from the instance <script> are NOT module members.
 	export interface ChipSuggestion {
 		label: string;
 		description?: string;
@@ -39,6 +31,21 @@
 		/** If true, insert as plain text instead of a chip element */
 		insertAsText?: boolean;
 	}
+</script>
+
+<script lang="ts">
+	/**
+	 * ChipInput - Generic contenteditable input with inline chips and autocomplete.
+	 *
+	 * Handles:
+	 * - Contenteditable div with placeholder
+	 * - Chip insertion/deletion (non-editable inline spans)
+	 * - Autocomplete dropdown with keyboard navigation
+	 * - Serialization (DOM -> text with chip markers)
+	 */
+
+	// --- Types (ChipSuggestion, SuggestionGroup, ChipInfo) are declared in the
+	// module <script> above so they are importable as module members. ---
 
 	// --- Props ---
 	let {

package/src/lib/components/Collapse.svelte

@@ -0,0 +1,82 @@
+<script lang="ts">
+	/**
+	 * Collapse — batteries-included tall-content collapser.
+	 *
+	 * Wraps children in a region that caps at `threshold` px with a fade-out
+	 * gradient and renders a "Show more / Show less" toggle that self-hides when
+	 * the content is shorter than the threshold. Uses the `collapse` action for
+	 * measurement (ResizeObserver-backed, so streaming / {@html} content works).
+	 *
+	 *   <Collapse>
+	 *     {@html renderedMarkdown}
+	 *   </Collapse>
+	 *
+	 * For existing elements you don't want to wrap (a bare `<p>` inside an
+	 * `{#each}`, a `<pre>`), use the `collapse` action directly instead.
+	 */
+	import { collapse } from '../actions/collapse';
+
+	interface Props {
+		/** Max collapsed height in px. Default 120. */
+		threshold?: number;
+		/** Where the fade begins, as a %. Default 55. */
+		fadeStart?: number;
+		/** Start expanded. Default false. */
+		expanded?: boolean;
+		/** Toggle label when collapsed. Default 'Show more ↓'. */
+		moreLabel?: string;
+		/** Toggle label when expanded. Default 'Show less ↑'. */
+		lessLabel?: string;
+		/** Extra classes on the content region. */
+		class?: string;
+		children?: import('svelte').Snippet;
+	}
+
+	let {
+		threshold = 120,
+		fadeStart = 55,
+		expanded = $bindable(false),
+		moreLabel = 'Show more ↓',
+		lessLabel = 'Show less ↑',
+		class: className = '',
+		children,
+	}: Props = $props();
+
+	let collapsible = $state(false);
+</script>
+
+<div
+	class={`jatui-collapse-body ${className}`.trim()}
+	use:collapse={{ threshold, fadeStart, expanded, onCollapsible: (c) => (collapsible = c) }}
+>
+	{#if children}
+		{@render children()}
+	{/if}
+</div>
+{#if collapsible}
+	<button type="button" class="jatui-collapse-toggle" onclick={() => (expanded = !expanded)}>
+		{expanded ? lessLabel : moreLabel}
+	</button>
+{/if}
+
+<style>
+	.jatui-collapse-body {
+		position: relative;
+	}
+	.jatui-collapse-toggle {
+		display: block;
+		margin-top: 4px;
+		padding: 2px 0;
+		font-size: 11px;
+		color: var(--color-primary, oklch(0.65 0.12 250));
+		background: none;
+		border: none;
+		cursor: pointer;
+		opacity: 0.75;
+		transition: opacity 0.1s;
+	}
+	.jatui-collapse-toggle:hover {
+		opacity: 1;
+		text-decoration: underline;
+	}
+</style>

package/src/lib/components/InlineEdit.svelte

@@ -1,3 +1,14 @@
+<script module lang="ts">
+	// Declared in the module script so `import type { DisplaySegment } from
+	// './InlineEdit.svelte'` resolves (instance-script exports are not module members).
+	/** A display segment for formula-aware rendering */
+	export interface DisplaySegment {
+		type: 'text' | 'formula';
+		display: string;
+		tooltip?: string;
+	}
+</script>
+
 <script lang="ts">
 	/**
 	 * InlineEdit Component
@@ -14,13 +25,6 @@
 	 * - Optional formula-aware display: segments with type/display/tooltip
 	 */
 
-	/** A display segment for formula-aware rendering */
-	export interface DisplaySegment {
-		type: 'text' | 'formula';
-		display: string;
-		tooltip?: string;
-	}
-
 	interface Props {
 		/** Current value */
 		value: string;

package/src/lib/components/linked-columns/LinkedColumns.svelte

@@ -1,3 +1,17 @@
+<script module lang="ts">
+	// Declared in the module script so `import type { ColumnLink } from
+	// './LinkedColumns.svelte'` resolves (instance-script exports are not module members).
+	/** Describes which left items a single right (anchor) item covers. */
+	export interface ColumnLink {
+		/** The right item's id this link belongs to. */
+		rightId: string | number;
+		/** First left item id in the covered range (inclusive). */
+		leftStartId: string | number;
+		/** Last left item id in the covered range (inclusive). */
+		leftEndId: string | number;
+	}
+</script>
+
 <script lang="ts" generics="L extends { id: string | number }, R extends { id: string | number }">
 	/**
 	 * LinkedColumns — generic two-column ink-up ribbon primitive.
@@ -51,15 +65,7 @@
 
 	import type { Snippet } from 'svelte';
 
-	/** Describes which left items a single right (anchor) item covers. */
-	export interface ColumnLink {
-		/** The right item's id this link belongs to. */
-		rightId: string | number;
-		/** First left item id in the covered range (inclusive). */
-		leftStartId: string | number;
-		/** Last left item id in the covered range (inclusive). */
-		leftEndId: string | number;
-	}
+	// ColumnLink is declared in the module <script> above so it's importable as a module member.
 
 	let {
 		leftItems,

package/src/lib/index.ts

@@ -1,6 +1,9 @@
 // Actions
 export { railNav, createRailNav, cycle } from './actions/railNav';
 export type { RailNavOptions, RailNavController } from './actions/railNav';
+export { collapse } from './actions/collapse';
+export type { CollapseOptions } from './actions/collapse';
+export { default as Collapse } from './components/Collapse.svelte';
 
 // Components — Session primitives (from JAT IDE, jat-jj79f.16 G1)
 export { default as LinkedColumns } from './components/linked-columns/LinkedColumns.svelte';