@octane-xplat/ui 0.9.0 → 0.10.0

package/src/nav-family.web.test.tsrx

@@ -0,0 +1,252 @@
+// @vitest-environment jsdom
+import { describe, expect, it, vi } from 'vitest';
+import { act, createRoot } from 'octane';
+import { NavIcon } from './NavIcon.web.tsrx';
+import { Toolbar } from './Toolbar.web.tsrx';
+
+function host() {
+	const el = document.createElement('div');
+	document.body.appendChild(el);
+	return { el, root: createRoot(el) };
+}
+
+describe('NavIcon (web leaf)', () => {
+	it('renders the circular container with the supplied icon', () => {
+		const { el, root } = host();
+		act(() => root.render(<NavIcon icon={<span className="test-glyph">x</span>} />));
+		const box = el.querySelector('.vx-navicon')!;
+		expect(box).toBeTruthy();
+		expect(box.querySelector('.test-glyph')).toBeTruthy();
+		root.unmount();
+		el.remove();
+	});
+});
+
+describe('Toolbar (web leaf)', () => {
+	it('renders role=toolbar with label and slot content', () => {
+		const { el, root } = host();
+		act(() =>
+			root.render(
+				<Toolbar label="Actions" startContent={<button type="button">Back</button>} endContent={<button type="button">Save</button>} />,
+			),
+		);
+
+		const bar = el.querySelector('[role="toolbar"]')!;
+		expect(bar.getAttribute('aria-label')).toBe('Actions');
+		expect(bar.getAttribute('aria-orientation')).toBe('horizontal');
+		expect(bar.querySelector('.vx-toolbar-slot--start')!.textContent).toBe('Back');
+		expect(bar.querySelector('.vx-toolbar-slot--end')!.textContent).toBe('Save');
+		root.unmount();
+		el.remove();
+	});
+
+	it('arrows move focus between items (roving tabindex)', () => {
+		const { el, root } = host();
+		act(() =>
+			root.render(
+				<Toolbar
+					label="Actions"
+					startContent={
+						<>
+							<button type="button">One</button>
+							<button type="button">Two</button>
+						</>
+					}
+				/>,
+			),
+		);
+
+		const buttons = el.querySelectorAll('button');
+		act(() => (buttons[0] as HTMLElement).focus());
+		act(() => {
+			buttons[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+		});
+
+		expect(document.activeElement).toBe(buttons[1]);
+		root.unmount();
+		el.remove();
+	});
+});
+
+import { AppShell } from './AppShell.web.tsrx';
+import { TopNav, TopNavItem } from './TopNav.web.tsrx';
+import { SideNav, SideNavItem, SideNavSection } from './SideNav.web.tsrx';
+import { MobileNav, MobileNavToggle } from './MobileNav.web.tsrx';
+import { NavHeadingMenu, NavHeadingMenuItem } from './NavMenu.web.tsrx';
+import { ResizeHandle } from './ResizeHandle.web.tsrx';
+import { useResizable } from './useResizable.web.tsrx';
+import { NavigationMenu } from './NavigationMenu.web.tsrx';
+
+describe('NavHeadingMenu (web leaf)', () => {
+	it('renders role=menu/menuitem and activates items via Enter', () => {
+		const { el, root } = host();
+		const hits: string[] = [];
+		act(() =>
+			root.render(
+				<NavHeadingMenu>
+					<NavHeadingMenuItem label="One" onClick={() => hits.push('one')} />
+					<NavHeadingMenuItem label="Two" isDisabled onClick={() => hits.push('two')} />
+					<NavHeadingMenuItem label="Three" onClick={() => hits.push('three')} />
+				</NavHeadingMenu>,
+			),
+		);
+
+		const menu = el.querySelector('[role="menu"]')!;
+		expect(menu).toBeTruthy();
+		const items = Array.from(el.querySelectorAll('[role="menuitem"]')) as HTMLElement[];
+		expect(items.length).toBe(3);
+		expect(items[1].getAttribute('aria-disabled')).toBe('true');
+		act(() => items[0].focus());
+		// typeahead: 't' skips disabled Two and lands on Three
+		act(() => {
+			items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 't', bubbles: true }));
+		});
+
+		expect(document.activeElement).toBe(items[2]);
+		act(() => {
+			items[2].dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+		});
+
+		expect(hits).toEqual(['three']);
+		root.unmount();
+		el.remove();
+	});
+
+	it('anchor items get real href navigation semantics', () => {
+		const { el, root } = host();
+		act(() =>
+			root.render(
+				<NavHeadingMenu>
+					<NavHeadingMenuItem label="Docs" href="/docs" />
+				</NavHeadingMenu>,
+			),
+		);
+
+		const item = el.querySelector('[role="menuitem"]') as HTMLAnchorElement;
+		expect(item.tagName).toBe('A');
+		expect(item.getAttribute('href')).toBe('/docs');
+		root.unmount();
+		el.remove();
+	});
+});
+
+describe('AppShell + TopNav + SideNav (web leaf)', () => {
+	it('lays out header/sidenav/content landmarks', () => {
+		const { el, root } = host();
+		act(() =>
+			root.render(
+				<AppShell
+					variant="surface"
+					mobileNav={false}
+					topNav={<TopNav heading={<span>Brand</span>} startContent={<TopNavItem label="Home" href="/" />} />}
+					sideNav={<SideNav><SideNavItem label="A" /></SideNav>}
+					banner={<span>Banner</span>}
+				>
+					<p>Body</p>
+				</AppShell>,
+			),
+		);
+
+		expect(el.querySelector('[role="banner"]')).toBeTruthy();
+		expect(el.querySelector('[role="main"]')).toBeTruthy();
+		expect(el.querySelector('.vx-appshell-sidenav')).toBeTruthy();
+		expect(el.querySelector('.vx-appshell-skiplink')).toBeTruthy();
+		root.unmount();
+		el.remove();
+	});
+
+	it('mobile toggle opens the drawer below the breakpoint', () => {
+		// jsdom has no matchMedia — the defaultIsMobile hint makes the shell mobile.
+		const { el, root } = host();
+		act(() =>
+			root.render(
+				<AppShell
+					mobileNav={{ defaultIsMobile: true }}
+					sideNav={<SideNav><SideNavItem label="A" /></SideNav>}
+				>
+					<p>Body</p>
+				</AppShell>,
+			),
+		);
+
+		const toggle = el.querySelector('.vx-mobilenav-toggle') as HTMLElement;
+		expect(toggle).toBeTruthy();
+		act(() => {
+			toggle.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+		});
+
+		const dialog = el.querySelector('dialog.vx-mobilenav') as HTMLDialogElement;
+		expect(dialog).toBeTruthy();
+		expect(dialog.hasAttribute('open') || dialog.open).toBeTruthy();
+		root.unmount();
+		el.remove();
+	});
+});
+
+describe('NavigationMenu (web leaf)', () => {
+	it('renders items with href as anchors and others as buttons', () => {
+		const { el, root } = host();
+		const hits: string[] = [];
+		act(() =>
+			root.render(
+				<NavigationMenu items={[
+					{ key: 'a', label: 'Alpha', href: '/a' },
+					{ key: 'b', label: 'Beta', onSelect: () => hits.push('b') },
+				]} />,
+			),
+		);
+
+		const items = el.querySelectorAll('.vx-navmenu-strip-item');
+		expect((items[0] as HTMLElement).tagName).toBe('A');
+		expect((items[1] as HTMLElement).tagName).toBe('BUTTON');
+		act(() => {
+			items[1].dispatchEvent(new MouseEvent('click', { bubbles: true }));
+		});
+
+		expect(hits).toEqual(['b']);
+		root.unmount();
+		el.remove();
+	});
+});
+
+describe('ResizeHandle + useResizable (web leaf)', () => {
+	function Harness(props: { onSize?: (n: number) => void }) {
+		const r = useResizable({ defaultSize: 200, minSize: 100, maxSize: 400, onSizeChange: props.onSize });
+		return (
+			<div>
+				<div className="probe">{String(r.size)}</div>
+				<ResizeHandle direction="horizontal" resizable={r.props} />
+			</div>
+		);
+	}
+
+	it('arrow keys resize by 10px steps (50 with shift), Home/End clamp', () => {
+		const { el, root } = host();
+		act(() => root.render(<Harness />));
+		const handle = el.querySelector('[role="separator"]') as HTMLElement;
+		expect(handle.getAttribute('aria-valuenow')).toBe('200');
+		act(() => handle.focus());
+		act(() => {
+			handle.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+		});
+
+		expect(handle.getAttribute('aria-valuenow')).toBe('210');
+		act(() => {
+			handle.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowLeft', shiftKey: true, bubbles: true }));
+		});
+
+		expect(handle.getAttribute('aria-valuenow')).toBe('160');
+		act(() => {
+			handle.dispatchEvent(new KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
+		});
+
+		expect(handle.getAttribute('aria-valuenow')).toBe('100');
+		act(() => {
+			handle.dispatchEvent(new KeyboardEvent('keydown', { key: 'End', bubbles: true }));
+		});
+
+		expect(handle.getAttribute('aria-valuenow')).toBe('400');
+		root.unmount();
+		el.remove();
+	});
+});

package/src/nav-href.macos.ts

@@ -0,0 +1,21 @@
+import { pushDeepLink } from './route.macos'
+
+/** AppKit leaf — app-relative hrefs go to the route table (its
+ *  `pushDeepLink` reports no match state, so the split is by shape):
+ *  scheme-qualified URLs ask the host bridge to open a browser window. */
+export function followHref(href: string): void {
+	if (!href) {
+		return
+	}
+
+	if (/^[a-z][a-z0-9+.-]*:/i.test(href)) {
+		const open = (globalThis as any).__xplatAppKitOpenWindow
+		if (typeof open === 'function') {
+			open({ url: href })
+		}
+
+		return
+	}
+
+	pushDeepLink(href)
+}

package/src/nav-href.ts

@@ -0,0 +1,30 @@
+import { Utils } from '@nativescript/core'
+import { pushDeepLink } from './route'
+
+/** Activate an `href` outside a real anchor: the route table wins (an app
+ *  deep link), then the platform URL opener for absolute URLs. Relative
+ *  hrefs that match no route warn once — there is no address bar to hand
+ *  them to on native. */
+const warned = new Set<string>()
+
+export function followHref(href: string): void {
+	if (!href) {
+		return
+	}
+
+	if (pushDeepLink(href)) {
+		return
+	}
+
+	if (/^[a-z][a-z0-9+.-]*:/i.test(href)) {
+		Utils.openUrl(href)
+		return
+	}
+
+	if (!warned.has(href)) {
+		warned.add(href)
+		console.warn(
+			`[octane-xplat] href '${href}' matched no route — relative links need a registered deep link (see docs/app/navigation.md).`,
+		)
+	}
+}

package/src/nav-href.web.ts

@@ -0,0 +1,16 @@
+import { pushDeepLink } from './route.web'
+
+/** Web fallback for programmatic href activation (non-anchor surfaces such
+ *  as menu items rendered as buttons). Anchors navigate natively, so this
+ *  path is only for elements that asked to handle activation themselves. */
+export function followHref(href: string): void {
+	if (!href) {
+		return
+	}
+
+	if (pushDeepLink(href)) {
+		return
+	}
+
+	window.location.href = href
+}

package/src/outline-dom.macos.tsrx

@@ -0,0 +1,26 @@
+/** @jsxImportSource @octane-xplat/macos-renderer */
+// macOS leaf — same duck-typed subtree walk as the mobile leaf (the AppKit
+// host exposes `children`/`subviews` on its view wrappers). No mutation
+// observation: collected on mount and when the container view changes.
+import { useEffect, useState } from 'octane'
+import type { OutlineFromDOMOptions, OutlineItem } from './props'
+import { outlineItemsFromViewTree } from './outline-view-tree'
+
+export function useOutlineFromDOM(containerRef?: unknown, _options?: OutlineFromDOMOptions): OutlineItem[] {
+	const [items, setItems] = useState<OutlineItem[]>([])
+
+	useEffect(() => {
+		const view = containerRef && typeof containerRef === 'object' && 'current' in containerRef
+			? (containerRef as { current?: any }).current
+			: containerRef
+
+		if (!view) {
+			setItems([])
+			return
+		}
+
+		setItems(outlineItemsFromViewTree(view))
+	})
+
+	return items
+}

package/src/outline-dom.tsrx

@@ -0,0 +1,32 @@
+/** @jsxImportSource @nativescript-community/octane */
+// Native leaf — no DOM or MutationObserver, so `useOutlineFromDOM` walks the
+// bound view subtree once it mounts (and re-walks when the container view
+// instance changes). Views with accessibilityRole 'header' contribute items.
+import { useEffect, useState } from 'octane'
+import type { OutlineFromDOMOptions, OutlineItem } from './props'
+import { outlineItemsFromViewTree } from './outline-view-tree'
+
+/** `useOutlineFromDOM` — native form. The DOM API name is kept for API
+ *  parity; the argument is a `ref`/`ref`-style object holding the scroll
+ *  container's (or page's) root view. There is no mutation observation on
+ *  the NS view tree, so the outline is collected once after mount and again
+ *  whenever `containerRef.current` changes — use `useOutlineFromMarkdown`
+ *  (or pass `items` directly) when the heading set is dynamic. */
+export function useOutlineFromDOM(containerRef?: unknown, _options?: OutlineFromDOMOptions): OutlineItem[] {
+	const [items, setItems] = useState<OutlineItem[]>([])
+
+	useEffect(() => {
+		const view = containerRef && typeof containerRef === 'object' && 'current' in containerRef
+			? (containerRef as { current?: any }).current
+			: containerRef
+
+		if (!view) {
+			setItems([])
+			return
+		}
+
+		setItems(outlineItemsFromViewTree(view))
+	})
+
+	return items
+}

package/src/outline-dom.web.tsrx

@@ -0,0 +1,63 @@
+// Web leaf — collects headings from a live DOM container and keeps them
+// current through MutationObserver. Only heading elements h1–h6 contribute;
+// `id` falls back to a slug derived from the heading text.
+import { useEffect, useMemo, useRef, useState } from 'octane'
+import type { OutlineFromDOMOptions, OutlineItem } from './props'
+import { slugify, uniqueSlug } from './outline-utils'
+
+/** Read the heading tree from a container (or the document) — each entry
+ *  carries the element's id (or a slug of its text) and its tag level. */
+export function outlineItemsFromDOM(
+	container?: ParentNode | null,
+	selector = 'h1, h2, h3, h4, h5, h6',
+): OutlineItem[] {
+	const root: ParentNode | undefined = container ?? (typeof document !== 'undefined' ? document : undefined)
+	if (!root) return []
+	const nodes = root.querySelectorAll(selector)
+	const counts = new Map<string, number>()
+	const items: OutlineItem[] = []
+	for (const node of nodes) {
+		const el = node as HTMLElement
+		const level = Number(el.tagName?.slice(1)) || 2
+		const label = (el.innerText ?? el.textContent ?? '').trim()
+		if (!label) continue
+		const id = el.id || uniqueSlug(slugify(label), counts)
+		items.push({ id, label, level })
+	}
+
+	return items
+}
+
+/** `useOutlineFromDOM` — keeps the item list in sync with the container's
+ *  heading nodes via MutationObserver. The container may be a ref object
+ *  (`{current}`) or a DOM node. */
+export function useOutlineFromDOM(
+	containerRef?: unknown,
+	options?: OutlineFromDOMOptions,
+): OutlineItem[] {
+	const [items, setItems] = useState<OutlineItem[]>([])
+	const resolve = () => {
+		const source = containerRef && typeof containerRef === 'object' && 'current' in containerRef
+			? (containerRef as { current?: unknown }).current
+			: containerRef
+
+		return (source ?? options?.root ?? (typeof document !== 'undefined' ? document : null)) as ParentNode | null
+	}
+
+	useEffect(() => {
+		const refresh = () => setItems(outlineItemsFromDOM(resolve(), options?.selector))
+		refresh()
+		const root = resolve()
+		const observer = new MutationObserver(refresh)
+		if (root) {
+			observer.observe(root as Node, { childList: true, subtree: true, characterData: true })
+		} else if (typeof document !== 'undefined') {
+			observer.observe(document.body, { childList: true, subtree: true, characterData: true })
+		}
+
+		return () => observer.disconnect()
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [options?.selector])
+
+	return items
+}

package/src/outline-hooks.tsrx

@@ -0,0 +1,21 @@
+// Portable outline hooks — shared across web and native leaves.
+// `useOutlineFromMarkdown` is identical on every target (pure parse); the
+// `useOutlineFromDOM` halves live in outline-dom.web.tsrx / outline-dom.tsrx
+// because only the web can observe a live DOM.
+import { useMemo } from 'octane'
+import { outlineFromDoc, parseOutlineFromMarkdown } from './outline-utils'
+import type { MdDoc } from './Markdown'
+import type { OutlineItem } from './props'
+
+/** Heading outline items derived from Markdown source — one entry per ATX or
+ *  Setext heading, labelled by the inline text, id'd by the deduplicated
+ *  slug (same slugify/uniqueSlug contract as upstream). */
+export function useOutlineFromMarkdown(markdown: string): OutlineItem[] {
+	return useMemo(() => parseOutlineFromMarkdown(markdown), [markdown])
+}
+
+/** Outline items from a baked `MdDoc` (the `xplat routes`/`Markdown` AST) —
+ *  the portable form of "outline the document I'm rendering". */
+export function useOutlineFromDoc(doc: MdDoc): OutlineItem[] {
+	return useMemo(() => outlineFromDoc(doc), [doc])
+}

package/src/outline-utils.ts

@@ -0,0 +1,181 @@
+// Outline data helpers — the portable half of Astryx's Outline utilities.
+// slugify/uniqueSlug are byte-identical to upstream (same ids). The markdown
+// scanner is a focused replacement for upstream's full parser pipeline: it
+// understands ATX and Setext headings, fenced/indented code, and strips the
+// inline constructs the local Markdown renderer supports. It has no plugin
+// surface (the local Markdown AST has no extension nodes — see
+// docs/app/components.md).
+import type { OutlineItem } from './props'
+export type { OutlineItem } from './props'
+import type { MdDoc, MdInline } from './Markdown'
+
+/** Slug a heading label the same way upstream's parser does: lowercase,
+ *  quotes dropped, non-alphanumerics collapse to '-', edges trimmed. */
+export function slugify(value: string): string {
+	return value
+		.trim()
+		.toLowerCase()
+		.replace(/['"]/g, '')
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+}
+
+/** Disambiguate repeated slugs with a numeric suffix (`setup`, `setup-1`, …).
+ *  Empty slugs fall back to `section`. The caller owns the counts map. */
+export function uniqueSlug(baseSlug: string, counts: Map<string, number>): string {
+	const fallbackSlug = baseSlug || 'section'
+	const count = counts.get(fallbackSlug) ?? 0
+	counts.set(fallbackSlug, count + 1)
+	return count === 0 ? fallbackSlug : `${fallbackSlug}-${count}`
+}
+
+// ---------------------------------------------------------------------------
+// Markdown heading extraction
+// ---------------------------------------------------------------------------
+
+const FENCE = /^(?:`{3,}|~{3,})/
+const ATX = /^ {0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/
+const SETEXT_H1 = /^ {0,3}=+[ \t]*$/
+const SETEXT_H2 = /^ {0,3}-+[ \t]*$/
+const BLANK = /^\s*$/
+
+/** Strip the inline constructs the local Markdown AST supports (code spans,
+ *  emphasis, links, images, escapes), leaving the visible text — matching
+ *  what `markdownAstText` produces upstream. */
+export function inlineMarkdownText(source: string): string {
+	let text = source
+	// Images first: ![alt](src) → alt (upstream keeps alt text only)
+	text = text.replace(/!\[([^\]]*)\]\([^)]*\)/g, '$1')
+	// Links: [text](href) → text
+	text = text.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+	// Inline code: `code` → code
+	text = text.replace(/`([^`]*)`/g, '$1')
+	// Bold/italic markers
+	text = text.replace(/\*\*([^*]+)\*\*/g, '$1')
+	text = text.replace(/__([^_]+)__/g, '$1')
+	text = text.replace(/\*([^*]+)\*/g, '$1')
+	text = text.replace(/\b_([^_]+)_\b/g, '$1')
+	// Strikethrough
+	text = text.replace(/~~([^~]+)~~/g, '$1')
+	// Backslash escapes
+	text = text.replace(/\\([\\`*{}[\]()#+\-.!_>~])/g, '$1')
+	// HTML tags are not rendered by the local Markdown AST — drop them.
+	text = text.replace(/<[^>]+>/g, '')
+	return text.trim()
+}
+
+interface ParsedHeading {
+	label: string
+	level: number
+}
+
+/**
+ * Scan markdown source for headings. Not a general parser — it exists to
+ * produce outline labels that agree with what the Markdown component renders
+ * for the same source. Fenced code blocks (```/~~~) and 4-space-indented
+ * lines are never headings; Setext underlines promote the previous
+ * non-blank line.
+ */
+export function markdownHeadings(markdown: string): ParsedHeading[] {
+	const headings: ParsedHeading[] = []
+	const lines = markdown.split('\n')
+	let fenced = false
+	let fenceMarker = ''
+	let previousTextLine = ''
+
+	for (const line of lines) {
+		const fenceMatch = line.match(FENCE)
+		if (fenceMatch) {
+			if (!fenced) {
+				fenced = true
+				fenceMarker = fenceMatch[0][0]
+			} else if (fenceMatch[0][0] === fenceMarker) {
+				fenced = false
+			}
+
+			previousTextLine = ''
+			continue
+		}
+
+		if (fenced) {
+			continue
+		}
+
+		const atx = line.match(ATX)
+		if (atx) {
+			headings.push({ label: inlineMarkdownText(atx[2]), level: atx[1].length })
+			previousTextLine = ''
+			continue
+		}
+
+		if (SETEXT_H1.test(line) || SETEXT_H2.test(line)) {
+			if (!BLANK.test(previousTextLine)) {
+				headings.push({
+					label: inlineMarkdownText(previousTextLine.trim()),
+					level: line.includes('=') ? 1 : 2,
+				})
+
+				previousTextLine = ''
+				continue
+			}
+		}
+
+		// 4-space indented lines are code blocks, never text.
+		previousTextLine = /^ {4}/.test(line) ? '' : line
+	}
+
+	return headings
+}
+
+/**
+ * Extract outline items from a Markdown string: heading text becomes the
+ * label, its slug (with per-document dedup) becomes the id. For
+ * `useOutlineFromMarkdown` parity on MdDoc-shaped data see
+ * {@link outlineFromDoc}.
+ */
+export function parseOutlineFromMarkdown(markdown: string): OutlineItem[] {
+	const counts = new Map<string, number>()
+	return markdownHeadings(markdown)
+		.filter((heading) => heading.label !== '')
+		.map((heading) => ({
+			id: uniqueSlug(slugify(heading.label), counts),
+			label: heading.label,
+			level: heading.level,
+		}))
+}
+
+function inlineNodesText(nodes: readonly MdInline[] | undefined): string {
+	let out = ''
+	for (const node of nodes ?? []) {
+		out +=
+			node.t === 'text' || node.t === 'code'
+				? node.text
+				: node.t === 'link'
+					? node.text
+					: inlineNodesText(node.children)
+	}
+
+	return out
+}
+
+/** Outline items from a baked `MdDoc` (the AST `xplat routes` produces and
+ *  the `Markdown` component renders) — the portable equivalent of deriving
+ *  an outline from rendered markdown content. */
+export function outlineFromDoc(doc: MdDoc): OutlineItem[] {
+	const counts = new Map<string, number>()
+	const items: OutlineItem[] = []
+	for (const node of doc.children ?? []) {
+		if (node.t !== 'h') {
+			continue
+		}
+
+		const label = inlineNodesText(node.children).trim()
+		if (!label) {
+			continue
+		}
+
+		items.push({ id: uniqueSlug(slugify(label), counts), label, level: node.depth })
+	}
+
+	return items
+}