@diegopluna/narvi 0.0.0-stage → 0.0.1

package/dist/components/conversation/ConversationRoot.svelte

@@ -0,0 +1,237 @@
+<script lang="ts" module>
+	import * as stylex from '@stylexjs/stylex';
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { attrs, type Sx } from '../../internal/sx.js';
+	import { colors, font } from '../../tokens.stylex.js';
+	import { setConversationContext } from './context.js';
+
+	export type ConversationRootProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+		/**
+		 * How near the bottom, in pixels, still counts as reading the latest. Within
+		 * it, the conversation picks up following again and the scroll button hides.
+		 */
+		threshold?: number;
+		sx?: Sx;
+		ref?: HTMLDivElement | null;
+		/** A Conversation.Content and a Conversation.ScrollButton. */
+		children?: Snippet;
+	};
+
+	const styles = stylex.create({
+		root: {
+			position: 'relative',
+			display: 'flex',
+			flexDirection: 'column',
+			minHeight: 0,
+			color: colors.text,
+			fontFamily: font.body
+		}
+	});
+</script>
+
+<script lang="ts">
+	import {
+		FOLLOW_BAND,
+		INTENT_WINDOW,
+		SELF_SCROLL_WINDOW,
+		isUpKey,
+		onScrollbar,
+		scrollsInside
+	} from './scrolling.js';
+	import type { ConversationMode } from './context.js';
+
+	let {
+		threshold = FOLLOW_BAND,
+		sx,
+		class: className,
+		ref = $bindable(null),
+		children,
+		...rest
+	}: ConversationRootProps = $props();
+
+	// How far the message before an anchored one peeks above it
+	const PEEK = 64;
+
+	let atBottom = $state(true);
+	let mode = $state<ConversationMode>('following');
+	let spacer = $state(0);
+	let viewport: HTMLElement | null = null;
+	let anchored: HTMLElement | null = null;
+	let lastTop = 0;
+	// When the person last made a gesture that scrolls up, and when the
+	// conversation last moved itself
+	let intentAt = -Infinity;
+	let selfAt = -Infinity;
+
+	const reduceMotion = () => matchMedia('(prefers-reduced-motion: reduce)').matches;
+	const distance = (el: HTMLElement) => el.scrollHeight - el.clientHeight - el.scrollTop;
+
+	function moveTo(top: number, behavior: ScrollBehavior = 'instant') {
+		if (!viewport) return;
+		selfAt = performance.now();
+		viewport.scrollTo({ top, behavior });
+	}
+
+	/**
+	 * Scrolls to the newest content and follows it again as it grows.
+	 * Smooth by default, unless the person has asked for less motion.
+	 */
+	export function scrollToBottom(behavior?: ScrollBehavior) {
+		if (!viewport) return;
+		anchored = null;
+		spacer = 0;
+		mode = 'following';
+		moveTo(viewport.scrollHeight, behavior ?? (reduceMotion() ? 'instant' : 'smooth'));
+	}
+
+	// Where an anchored message sits in the scroller's own coordinates
+	function topOf(message: HTMLElement) {
+		if (!viewport) return 0;
+		return (
+			message.getBoundingClientRect().top -
+			viewport.getBoundingClientRect().top +
+			viewport.scrollTop
+		);
+	}
+
+	// The room needed beneath the content so the anchored message can reach the top
+	function settleSpacer() {
+		if (!viewport || !anchored) return;
+		if (!anchored.isConnected) {
+			anchored = null;
+			spacer = 0;
+			return;
+		}
+		const target = Math.max(0, topOf(anchored) - PEEK);
+		const natural = viewport.scrollHeight - spacer;
+		const needed = Math.max(0, Math.ceil(target + viewport.clientHeight - natural));
+		if (needed === 0) {
+			// The reply has outgrown the room: follow it from here
+			anchored = null;
+			spacer = 0;
+			if (mode === 'anchored') mode = 'following';
+			return;
+		}
+		spacer = needed;
+	}
+
+	/**
+	 * Lifts a message to the top of the view, with the one before it peeking
+	 * above, and leaves room beneath for the reply.
+	 */
+	export function anchor(message: HTMLElement, behavior?: ScrollBehavior) {
+		if (!viewport) return;
+		anchored = message;
+		mode = 'anchored';
+		settleSpacer();
+		// The spacer is laid out before the scroll, so there is room to reach the target
+		requestAnimationFrame(() => {
+			if (!anchored) return;
+			moveTo(
+				Math.max(0, topOf(anchored) - PEEK),
+				behavior ?? (reduceMotion() ? 'instant' : 'smooth')
+			);
+		});
+	}
+
+	function attach(el: HTMLElement, content: HTMLElement) {
+		viewport = el;
+		// Open at the latest message
+		moveTo(el.scrollHeight);
+		lastTop = el.scrollTop;
+
+		const intend = () => (intentAt = performance.now());
+
+		const onwheel = (event: WheelEvent) => {
+			if (event.deltaY < 0 && !scrollsInside(event.target, el, event.deltaY)) intend();
+		};
+		const onkeydown = (event: KeyboardEvent) => {
+			if (isUpKey(event)) intend();
+		};
+		const onpointerdown = (event: PointerEvent) => {
+			if (onScrollbar(event, el)) intend();
+		};
+		let touchY = 0;
+		const ontouchstart = (event: TouchEvent) => (touchY = event.touches[0]?.clientY ?? 0);
+		const ontouchmove = (event: TouchEvent) => {
+			const y = event.touches[0]?.clientY ?? 0;
+			// A finger moving down scrolls the content up
+			if (y > touchY && !scrollsInside(event.target, el, -1)) intend();
+			touchY = y;
+		};
+
+		const onscroll = () => {
+			const now = performance.now();
+			const top = el.scrollTop;
+			const away = distance(el);
+			const theirs = now - intentAt < INTENT_WINDOW && now - selfAt > SELF_SCROLL_WINDOW;
+			if (top < lastTop - 0.5 && theirs) {
+				// The person went up: let go, and stop holding a message at the top
+				mode = 'free';
+			} else if (mode === 'free' && away <= threshold) {
+				mode = 'following';
+				anchored = null;
+				spacer = 0;
+			}
+			atBottom = away <= threshold;
+			lastTop = top;
+		};
+
+		// New content, a streamed word or a resized window. The observer reports
+		// after layout and before paint, so correcting here never shows a frame
+		// at the old position.
+		const observer = new ResizeObserver(() => {
+			settleSpacer();
+			if (mode === 'following') moveTo(el.scrollHeight);
+			atBottom = mode === 'following' || distance(el) <= threshold;
+			lastTop = el.scrollTop;
+		});
+		observer.observe(content);
+		observer.observe(el);
+
+		el.addEventListener('scroll', onscroll, { passive: true });
+		el.addEventListener('wheel', onwheel, { passive: true });
+		el.addEventListener('keydown', onkeydown);
+		el.addEventListener('pointerdown', onpointerdown);
+		el.addEventListener('touchstart', ontouchstart, { passive: true });
+		el.addEventListener('touchmove', ontouchmove, { passive: true });
+
+		return () => {
+			observer.disconnect();
+			el.removeEventListener('scroll', onscroll);
+			el.removeEventListener('wheel', onwheel);
+			el.removeEventListener('keydown', onkeydown);
+			el.removeEventListener('pointerdown', onpointerdown);
+			el.removeEventListener('touchstart', ontouchstart);
+			el.removeEventListener('touchmove', ontouchmove);
+			if (viewport === el) viewport = null;
+		};
+	}
+
+	setConversationContext({
+		get atBottom() {
+			return atBottom;
+		},
+		get mode() {
+			return mode;
+		},
+		get spacer() {
+			return spacer;
+		},
+		scrollToBottom,
+		anchor,
+		attach
+	});
+</script>
+
+<div
+	bind:this={ref}
+	data-slot="conversation"
+	data-at-bottom={atBottom || undefined}
+	data-mode={mode}
+	{...rest}
+	{...attrs([styles.root, sx], className)}
+>
+	{@render children?.()}
+</div>

package/dist/components/conversation/ConversationRoot.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type Sx } from '../../internal/sx.js';
+export type ConversationRootProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    /**
+     * How near the bottom, in pixels, still counts as reading the latest. Within
+     * it, the conversation picks up following again and the scroll button hides.
+     */
+    threshold?: number;
+    sx?: Sx;
+    ref?: HTMLDivElement | null;
+    /** A Conversation.Content and a Conversation.ScrollButton. */
+    children?: Snippet;
+};
+declare const ConversationRoot: import("svelte").Component<ConversationRootProps, {
+    scrollToBottom: (behavior?: ScrollBehavior) => void;
+    anchor: (message: HTMLElement, behavior?: ScrollBehavior) => void;
+}, "ref">;
+type ConversationRoot = ReturnType<typeof ConversationRoot>;
+export default ConversationRoot;

package/dist/components/conversation/ConversationScrollButton.svelte

@@ -0,0 +1,114 @@
+<script lang="ts" module>
+	import * as stylex from '@stylexjs/stylex';
+	import type { Snippet } from 'svelte';
+	import type { HTMLButtonAttributes } from 'svelte/elements';
+	import Glyph from '../../internal/Glyph.svelte';
+	import { shared } from '../../internal/shared.js';
+	import { attrs, type Sx } from '../../internal/sx.js';
+	import { colors, font, motion, radius } from '../../tokens.stylex.js';
+	import { useConversation } from './context.js';
+
+	export type ConversationScrollButtonProps = Omit<HTMLButtonAttributes, 'children'> & {
+		/** Accessible name. Also shown beside the arrow when there are `children`. */
+		label?: string;
+		sx?: Sx;
+		ref?: HTMLButtonElement | null;
+		/** Text beside the arrow, such as "New messages". Leave it out for a round arrow button. */
+		children?: Snippet;
+	};
+
+	const HOVER = '@media (hover: hover) and (pointer: fine)';
+	const MOTION = '@media (prefers-reduced-motion: no-preference)';
+
+	const styles = stylex.create({
+		button: {
+			position: 'absolute',
+			insetInline: 0,
+			bottom: '1rem',
+			zIndex: 1,
+			display: 'inline-flex',
+			alignItems: 'center',
+			justifyContent: 'center',
+			gap: '0.375rem',
+			width: 'fit-content',
+			height: '2rem',
+			minWidth: '2rem',
+			marginInline: 'auto',
+			paddingInline: '0.5rem',
+			borderWidth: 0,
+			borderRadius: radius.full,
+			backgroundColor: colors.bgRaised,
+			color: {
+				default: colors.textMuted,
+				':hover': { default: null, [HOVER]: colors.text }
+			},
+			boxShadow: `inset 0 0 0 1px ${colors.lineStrong}, inset 0 1px 0 ${colors.highlight}, 0 1px 2px ${colors.shade}, 0 8px 20px -8px ${colors.shade}`,
+			fontFamily: font.body,
+			fontSize: font.sizeSm,
+			fontWeight: font.weightMedium,
+			lineHeight: 1,
+			whiteSpace: 'nowrap',
+			cursor: 'pointer',
+			WebkitTapHighlightColor: 'transparent',
+			// It rises into place, and drops away a little faster than it came
+			opacity: 1,
+			translate: '0 0',
+			scale: { default: null, ':active': { default: null, [MOTION]: 0.96 } },
+			transitionProperty: {
+				default: 'opacity, color',
+				[MOTION]: 'opacity, translate, scale, color'
+			},
+			transitionDuration: motion.slow,
+			transitionTimingFunction: motion.easeOut
+		},
+		withText: {
+			paddingInlineStart: '0.625rem',
+			paddingInlineEnd: '0.75rem'
+		},
+		hidden: {
+			opacity: 0,
+			translate: { default: null, [MOTION]: '0 8px' },
+			scale: { default: null, [MOTION]: 0.94 },
+			pointerEvents: 'none',
+			transitionDuration: motion.base
+		}
+	});
+</script>
+
+<script lang="ts">
+	let {
+		label = 'Scroll to the latest message',
+		sx,
+		class: className,
+		ref = $bindable(null),
+		children,
+		onclick,
+		...rest
+	}: ConversationScrollButtonProps = $props();
+
+	const conversation = useConversation('ScrollButton');
+	const hidden = $derived(conversation.atBottom);
+</script>
+
+<!-- Hidden while the latest message is in view. It stays in the page so it can
+     fade, but is inert so it cannot be reached. -->
+<button
+	bind:this={ref}
+	type="button"
+	aria-label={children ? undefined : label}
+	inert={hidden}
+	data-slot="conversation-scroll-button"
+	data-hidden={hidden || undefined}
+	{...rest}
+	{...attrs(
+		[styles.button, shared.focusable, children && styles.withText, hidden && styles.hidden, sx],
+		className
+	)}
+	onclick={(event) => {
+		onclick?.(event);
+		if (!event.defaultPrevented) conversation.scrollToBottom();
+	}}
+>
+	<Glyph name="arrowDown" size={16} stroke={1.75} />
+	{@render children?.()}
+</button>

package/dist/components/conversation/ConversationScrollButton.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+import { type Sx } from '../../internal/sx.js';
+export type ConversationScrollButtonProps = Omit<HTMLButtonAttributes, 'children'> & {
+    /** Accessible name. Also shown beside the arrow when there are `children`. */
+    label?: string;
+    sx?: Sx;
+    ref?: HTMLButtonElement | null;
+    /** Text beside the arrow, such as "New messages". Leave it out for a round arrow button. */
+    children?: Snippet;
+};
+declare const ConversationScrollButton: import("svelte").Component<ConversationScrollButtonProps, {}, "ref">;
+type ConversationScrollButton = ReturnType<typeof ConversationScrollButton>;
+export default ConversationScrollButton;

package/dist/components/conversation/context.d.ts

@@ -0,0 +1,28 @@
+/**
+ * How the conversation moves as content arrives.
+ * - `following`: it keeps the newest content in view
+ * - `free`: the person scrolled away; nothing moves under them
+ * - `anchored`: a message was lifted to the top, and the reply grows beneath it
+ */
+export type ConversationMode = 'following' | 'free' | 'anchored';
+export type ConversationContext = {
+    /** True while the newest content is in view. */
+    readonly atBottom: boolean;
+    readonly mode: ConversationMode;
+    /** Room left below the content while a message is anchored, in pixels. */
+    readonly spacer: number;
+    /** Scrolls to the newest content and follows it again as it grows. */
+    scrollToBottom(behavior?: ScrollBehavior): void;
+    /**
+     * Lifts a message to the top of the view, with the one before it peeking
+     * above, and leaves room beneath for the reply. Call it with the message the
+     * person just sent. Once the reply outgrows the room, the view follows it.
+     */
+    anchor(message: HTMLElement, behavior?: ScrollBehavior): void;
+    /** @internal Conversation.Content hands over its scroller and its content. */
+    attach(viewport: HTMLElement, content: HTMLElement): () => void;
+};
+export declare function setConversationContext(context: ConversationContext): void;
+/** The surrounding Conversation, for building parts of your own. */
+export declare function getConversationContext(): ConversationContext | undefined;
+export declare function useConversation(part: string): ConversationContext;

package/dist/components/conversation/context.js

@@ -0,0 +1,15 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('narvi.conversation');
+export function setConversationContext(context) {
+    setContext(KEY, context);
+}
+/** The surrounding Conversation, for building parts of your own. */
+export function getConversationContext() {
+    return getContext(KEY);
+}
+export function useConversation(part) {
+    const context = getConversationContext();
+    if (!context)
+        throw new Error(`<Conversation.${part}> must be placed inside <Conversation.Root>.`);
+    return context;
+}

package/dist/components/conversation/index.d.ts

@@ -0,0 +1,11 @@
+import Content from './ConversationContent.svelte';
+import Empty from './ConversationEmpty.svelte';
+import Root from './ConversationRoot.svelte';
+import ScrollButton from './ConversationScrollButton.svelte';
+export { Root, Content, ScrollButton, Empty, Root as ConversationRoot, Content as ConversationContent, ScrollButton as ConversationScrollButton, Empty as ConversationEmpty };
+export { getConversationContext } from './context.js';
+export type { ConversationContext, ConversationMode } from './context.js';
+export type { ConversationContentProps } from './ConversationContent.svelte';
+export type { ConversationEmptyProps } from './ConversationEmpty.svelte';
+export type { ConversationRootProps } from './ConversationRoot.svelte';
+export type { ConversationScrollButtonProps } from './ConversationScrollButton.svelte';

package/dist/components/conversation/index.js

@@ -0,0 +1,8 @@
+import Content from './ConversationContent.svelte';
+import Empty from './ConversationEmpty.svelte';
+import Root from './ConversationRoot.svelte';
+import ScrollButton from './ConversationScrollButton.svelte';
+export { Root, Content, ScrollButton, Empty, 
+//
+Root as ConversationRoot, Content as ConversationContent, ScrollButton as ConversationScrollButton, Empty as ConversationEmpty };
+export { getConversationContext } from './context.js';

package/dist/components/conversation/scrolling.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Telling the person's scrolling apart from the page's own.
+ *
+ * Content arriving, a code block folding open or the window resizing all move
+ * scrollTop too, and none of them should stop the conversation following. Only
+ * a gesture that means "take me up" does: a wheel or a swipe upward, the keys
+ * that scroll up, or a drag of the scrollbar. These rules come from Eregion,
+ * where each one fixed a reported jump.
+ */
+/** How long a gesture counts as the person's, after they make it. */
+export declare const INTENT_WINDOW = 1500;
+/** How long after the conversation moves itself its own scroll events are ignored. */
+export declare const SELF_SCROLL_WINDOW = 180;
+/** How near the end, in pixels, counts as at the end: following picks up again there. */
+export declare const FOLLOW_BAND = 40;
+/**
+ * Whether a wheel or swipe in this direction will be taken by something inside
+ * the conversation that can still scroll that way: a long code block, a table,
+ * a command's output. Then the conversation itself is not being scrolled.
+ */
+export declare function scrollsInside(target: EventTarget | null, viewport: HTMLElement, deltaY: number): boolean;
+/** Whether a key press asks the conversation to scroll up. */
+export declare function isUpKey(event: KeyboardEvent): boolean;
+/** Whether a press landed on the viewport's own scrollbar rather than its content. */
+export declare function onScrollbar(event: PointerEvent, viewport: HTMLElement): boolean;

package/dist/components/conversation/scrolling.js

@@ -0,0 +1,60 @@
+/**
+ * Telling the person's scrolling apart from the page's own.
+ *
+ * Content arriving, a code block folding open or the window resizing all move
+ * scrollTop too, and none of them should stop the conversation following. Only
+ * a gesture that means "take me up" does: a wheel or a swipe upward, the keys
+ * that scroll up, or a drag of the scrollbar. These rules come from Eregion,
+ * where each one fixed a reported jump.
+ */
+/** Keys that scroll a page up. Shift+Space is handled on its own. */
+const UP_KEYS = new Set(['ArrowUp', 'PageUp', 'Home']);
+/** How long a gesture counts as the person's, after they make it. */
+export const INTENT_WINDOW = 1500;
+/** How long after the conversation moves itself its own scroll events are ignored. */
+export const SELF_SCROLL_WINDOW = 180;
+/** How near the end, in pixels, counts as at the end: following picks up again there. */
+export const FOLLOW_BAND = 40;
+/**
+ * Whether a wheel or swipe in this direction will be taken by something inside
+ * the conversation that can still scroll that way: a long code block, a table,
+ * a command's output. Then the conversation itself is not being scrolled.
+ */
+export function scrollsInside(target, viewport, deltaY) {
+    let element = target instanceof Element ? target : null;
+    while (element && element !== viewport) {
+        if (element instanceof HTMLElement && element.scrollHeight > element.clientHeight) {
+            const overflow = getComputedStyle(element).overflowY;
+            if (overflow === 'auto' || overflow === 'scroll') {
+                if (deltaY < 0 && element.scrollTop > 0)
+                    return true;
+                if (deltaY > 0 && element.scrollTop + element.clientHeight < element.scrollHeight - 1)
+                    return true;
+            }
+        }
+        element = element.parentElement;
+    }
+    return false;
+}
+function isEditable(target) {
+    return (target instanceof HTMLElement &&
+        (target.isContentEditable || target.matches('input, textarea, select')));
+}
+/** Whether a key press asks the conversation to scroll up. */
+export function isUpKey(event) {
+    if (event.defaultPrevented || isEditable(event.target))
+        return false;
+    if (event.key === ' ')
+        return event.shiftKey;
+    return UP_KEYS.has(event.key) && !event.altKey && !event.metaKey && !event.ctrlKey;
+}
+/** Whether a press landed on the viewport's own scrollbar rather than its content. */
+export function onScrollbar(event, viewport) {
+    if (event.target !== viewport)
+        return false;
+    const box = viewport.getBoundingClientRect();
+    const inlineEnd = getComputedStyle(viewport).direction === 'rtl'
+        ? event.clientX - box.left
+        : box.right - event.clientX;
+    return inlineEnd <= viewport.offsetWidth - viewport.clientWidth;
+}

package/dist/components/dev-styles/DevStyles.svelte

@@ -0,0 +1,21 @@
+<!--
+	Loads the stylesheet the Narvi Vite plugin serves during development, and keeps
+	it fresh on hot updates. Renders nothing in production, where the styles are
+	already part of your CSS bundle. Mount it once, in your root layout.
+-->
+<script lang="ts">
+	import { DEV } from 'esm-env';
+
+	if (DEV) {
+		$effect(() => {
+			// @ts-expect-error virtual module provided by the Narvi Vite plugin
+			void import('virtual:stylex:runtime');
+		});
+	}
+</script>
+
+<svelte:head>
+	{#if DEV}
+		<link rel="stylesheet" href="/virtual:stylex.css" />
+	{/if}
+</svelte:head>

package/dist/components/dev-styles/DevStyles.svelte.d.ts

@@ -0,0 +1,3 @@
+declare const DevStyles: import("svelte").Component<Record<string, never>, {}, "">;
+type DevStyles = ReturnType<typeof DevStyles>;
+export default DevStyles;