@maple-kit/ui 0.1.0

package/dist/picker/picker.js

@@ -0,0 +1,164 @@
+import { useMapleUi } from "../context.js";
+import { useShots } from "../shots.js";
+import { PICK_ORDER } from "../island/language.js";
+import { ringLabel } from "../marks/label.js";
+import { MapleTargetRing } from "../marks/ring.js";
+import { PICKER_COPY, PICK_HINTS, pickerLabel } from "./language.js";
+import { startSession } from "./session.js";
+import { elementOf, targetFor } from "./target.js";
+import { Fragment, createElement, useCallback, useEffect, useRef, useState } from "react";
+import { captureContext, watchPickKeys } from "@maple-kit/core/overlay";
+import { useMaple, useMapleClient } from "@maple-kit/react";
+import { captureElement } from "@maple-kit/core/screenshot";
+import { sourceFor } from "@maple-kit/core/anchor";
+//#region src/picker/picker.ts
+const PART = "Maple.Picker";
+function MaplePicker(props) {
+	const { detail, pick } = useMaple();
+	const client = useMapleClient();
+	const { container, root } = useMapleUi(PART);
+	const [hovered, setHovered] = useState();
+	const [band, setBand] = useState();
+	const kind = pick.kind;
+	const commit = useCommit();
+	useEffect(() => {
+		if (!pick.armed || !kind) return;
+		const stop = new AbortController();
+		startSession(kind, stop.signal, {
+			ignore: (event) => onOwnControl(event, root),
+			onHover: setHovered,
+			onDraw: setBand,
+			onPick: (found) => commit(found)
+		});
+		return () => {
+			stop.abort();
+			setHovered(void 0);
+			setBand(void 0);
+		};
+	}, [
+		commit,
+		kind,
+		pick.armed,
+		root
+	]);
+	useKeys(pick.armed, kind, client);
+	if (!pick.armed || !kind) return null;
+	return createElement(Fragment, null, kind === "text" ? null : createElement("div", { className: shieldClass(props, kind) }), band ? createElement("div", {
+		className: "mk-band",
+		style: bandStyle(band)
+	}) : null, createElement(MapleTargetRing, {
+		state: "hovered",
+		target: targetOf(hovered),
+		...named(hovered, container, detail)
+	}), props.hint === false ? null : createElement(Hint, { kind }));
+}
+function useCommit() {
+	const client = useMapleClient();
+	const shots = useShots();
+	return useCallback((pick) => {
+		const target = targetFor(pick, { page: captureContext() });
+		const element = elementOf(pick);
+		if (shots && element) capture(element, shots);
+		client.disarm();
+		if (target) client.openComposer(target);
+	}, [client, shots]);
+}
+function capture(element, shots) {
+	captureElement(element, { page: true }).then((blob) => shots.put({
+		status: "taken",
+		image: {
+			blob,
+			type: blob.type
+		}
+	}), (error) => shots.put({
+		status: "failed",
+		reason: reasonOf(error)
+	}));
+}
+function reasonOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function useKeys(armed, kind, client) {
+	const latest = useRef(kind);
+	latest.current = kind;
+	useEffect(() => {
+		if (!armed) return;
+		const stop = new AbortController();
+		watchPickKeys({
+			signal: stop.signal,
+			onCancel: () => client.disarm(),
+			onCycle: () => client.arm(next(latest.current))
+		});
+		return () => stop.abort();
+	}, [armed, client]);
+}
+function onOwnControl(event, root) {
+	const target = event.composedPath()[0];
+	if (!(target instanceof Element) || target.getRootNode() !== root) return false;
+	return !target.classList.contains("mk-shield");
+}
+function next(kind) {
+	const at = kind === void 0 ? -1 : PICK_ORDER.indexOf(kind);
+	return PICK_ORDER[(at + 1) % PICK_ORDER.length] ?? "element";
+}
+function Hint(props) {
+	const client = useMapleClient();
+	return createElement("div", {
+		className: "mk-pick-bar",
+		role: "status",
+		"aria-label": pickerLabel(props.kind)
+	}, createElement("span", { className: "mk-pick-say" }, PICK_HINTS[props.kind]), createElement("span", { className: "mk-pick-kinds" }, ...PICK_ORDER.map((kind) => createElement("button", {
+		key: kind,
+		type: "button",
+		className: "mk-pick-kind mk-hit",
+		"aria-pressed": kind === props.kind,
+		onClick: () => client.arm(kind)
+	}, kind))), createElement("button", {
+		type: "button",
+		className: "mk-pick-stop mk-hit",
+		onClick: () => client.disarm()
+	}, PICKER_COPY.cancel, createElement("kbd", { className: "mk-kbd" }, PICKER_COPY.cancelHint)));
+}
+function shieldClass(props, kind) {
+	return [
+		"mk-shield",
+		kind === "region" && "mk-shield-drag",
+		props.className
+	].filter(Boolean).join(" ");
+}
+function targetOf(pick) {
+	if (!pick) return null;
+	if (pick.kind === "element") return pick.element;
+	return pick.kind === "text" ? pick.range : null;
+}
+function named(pick, container, detail) {
+	if (!pick) return {};
+	const found = targetFor(pick, { root: container.ownerDocument });
+	const on = {
+		...found ? { anchor: found.anchor } : {},
+		element: elementOf(pick) ?? null
+	};
+	const note = detail === "developer" ? sourceFor(on) : void 0;
+	const label = found === void 0 ? void 0 : ringLabel({
+		kind: pick.kind,
+		element: on.element,
+		...found.label === void 0 ? {} : { named: found.label }
+	});
+	return {
+		...label === void 0 ? {} : { label },
+		...note === void 0 ? {} : { note }
+	};
+}
+function bandStyle(rect) {
+	return {
+		"--mk-x": px(rect.x),
+		"--mk-y": px(rect.y),
+		"--mk-w": px(rect.width),
+		"--mk-h": px(rect.height)
+	};
+}
+function px(value) {
+	return `${String(value)}px`;
+}
+//#endregion
+export { MaplePicker, onOwnControl };

package/dist/picker/session.d.ts

@@ -0,0 +1,16 @@
+import { PickKind } from "@maple-kit/core/client";
+import { Pick, Rect } from "@maple-kit/core/overlay";
+//#region src/picker/session.d.ts
+/** What a running session reports back. */
+export interface SessionHandlers {
+  /** True for an event on the overlay's own controls, which is never a pick. */
+  readonly ignore: (event: Event) => boolean;
+  /** The pointer moved over something pickable, or off everything. */
+  readonly onHover: (pick: Pick | undefined) => void;
+  /** A rectangle being dragged, so the band can be drawn as it grows. */
+  readonly onDraw: (rect: Rect | undefined) => void;
+  readonly onPick: (pick: Pick) => void;
+}
+/** Starts the listeners for one kind. Aborting the signal removes every one. */
+export declare function startSession(kind: PickKind, signal: AbortSignal, handlers: SessionHandlers): void;
+//#endregion

package/dist/picker/session.js

@@ -0,0 +1,35 @@
+import { startElementPicking, startRegionPicking, startTextPicking } from "@maple-kit/core/overlay";
+//#region src/picker/session.ts
+function startSession(kind, signal, handlers) {
+	if (kind === "element") return element(signal, handlers);
+	return kind === "region" ? region(signal, handlers) : text(signal, handlers);
+}
+function element(signal, handlers) {
+	startElementPicking({
+		signal,
+		ignore: handlers.ignore,
+		onHover: handlers.onHover,
+		onPick: handlers.onPick
+	});
+}
+function region(signal, handlers) {
+	startRegionPicking({
+		signal,
+		ignore: handlers.ignore,
+		onDraw: handlers.onDraw,
+		onPick: (pick) => {
+			handlers.onDraw(void 0);
+			handlers.onPick(pick);
+		}
+	});
+}
+function text(signal, handlers) {
+	startTextPicking({
+		signal,
+		ignore: handlers.ignore,
+		onHover: handlers.onHover,
+		onPick: handlers.onPick
+	});
+}
+//#endregion
+export { startSession };

package/dist/picker/target.d.ts

@@ -0,0 +1,23 @@
+import { ComposerTarget } from "@maple-kit/core/client";
+import { PageContext, Pick } from "@maple-kit/core/overlay";
+//#region src/picker/target.d.ts
+/** What the anchor is described against, and the page as it was at pick time. */
+export interface TargetOptions {
+  /** Defaults to the picked element's own document. */
+  readonly root?: ParentNode;
+  /** Recorded with the comment. Captured by the caller, so a test can hand one in. */
+  readonly page?: PageContext;
+}
+/**
+ * The element a pick is about. For a region it is the box the rectangle was
+ * drawn inside, which is what its fractions are measured against and not what
+ * the comment is about.
+ */
+export declare function elementOf(pick: Pick): Element | undefined;
+/**
+ * The target, or nothing when a passage sat in no element at all. A region
+ * always has one: `containerFor` walks up to `documentElement` if it must, and
+ * a rectangle over the page's own background is still a rectangle.
+ */
+export declare function targetFor(pick: Pick, options?: TargetOptions): ComposerTarget | undefined;
+//#endregion

package/dist/picker/target.js

@@ -0,0 +1,37 @@
+import { toCommentContext } from "@maple-kit/core/overlay";
+import { describeElement, describeRange, labelFor, regionOf } from "@maple-kit/core/anchor";
+//#region src/picker/target.ts
+function elementOf(pick) {
+	return pick.kind === "text" ? rangeElement(pick.range) : pick.element;
+}
+function targetFor(pick, options = {}) {
+	const element = elementOf(pick);
+	if (!element) return void 0;
+	const anchor = anchorFor(pick, element, options.root);
+	const label = labelFor({
+		element,
+		anchor
+	});
+	return {
+		kind: pick.kind,
+		anchor,
+		...label === void 0 ? {} : { label },
+		...options.page === void 0 ? {} : { context: toCommentContext(options.page) }
+	};
+}
+function anchorFor(pick, element, root) {
+	const options = root === void 0 ? {} : { root };
+	if (pick.kind === "text") return describeRange(pick.range, options);
+	const described = describeElement(element, options);
+	if (pick.kind !== "region") return described;
+	return {
+		...described,
+		region: regionOf(pick.rect, element.getBoundingClientRect())
+	};
+}
+function rangeElement(range) {
+	const node = range.commonAncestorContainer;
+	return node instanceof Element ? node : node.parentElement ?? void 0;
+}
+//#endregion
+export { elementOf, targetFor };

package/dist/root.d.ts

@@ -0,0 +1,42 @@
+import { ReactNode } from "react";
+import { MapleClient, MapleClientOptions, MapleProps, ThemePreference } from "@maple-kit/core/client";
+//#region src/root.d.ts
+/**
+ * `auto` is the opposite of the host's scheme, not the same as it.
+ *
+ * Re-exported from `@maple-kit/core/client` so a part can name the type
+ * without importing the controller's entrypoint for it.
+ */
+type ThemePreference$1 = ThemePreference;
+/** How the overlay is mounted, and what it is pointed at. */
+export interface MapleRootProps extends MapleProps {
+  /** The branch the comments belong to. */
+  readonly branch: string;
+  /**
+   * What a reviewer calls this surface — a ticket, or the branch shortened to
+   * a hostname label. Read wherever the branch would be; the branch stays.
+   */
+  readonly label?: string;
+  /** The commit the preview is serving, where the build stamps one. */
+  readonly commit?: string;
+  readonly children?: ReactNode;
+  /** Added to the overlay's own layer, inside the shadow root. */
+  readonly className?: string;
+  /**
+   * The default the viewer starts on, `auto` unless given. Their own choice,
+   * made in the island's settings, is remembered per origin and wins.
+   */
+  readonly theme?: ThemePreference$1;
+  /** Everything else the controller takes. The three above win over it. */
+  readonly options?: Omit<MapleClientOptions, "branch" | "label" | "commit">;
+  /** A controller the caller built and owns, started and destroyed by them. */
+  readonly client?: MapleClient;
+  /** For a host that mounts Maple with a script tag rather than a bundle. */
+  readonly nonce?: string;
+  /** Where the overlay's container is appended. Defaults to `document.body`. */
+  readonly parent?: Element;
+}
+/** Mounts the overlay and puts its shadow root and controller in scope. */
+export declare const MapleRoot: import("react").ForwardRefExoticComponent<MapleRootProps & import("react").RefAttributes<HTMLDivElement>>;
+//#endregion
+export { ThemePreference$1 as ThemePreference };

package/dist/root.js

@@ -0,0 +1,75 @@
+import { MapleUiContext } from "./context.js";
+import { ShotContext, createShotStore } from "./shots.js";
+import { OVERLAY_CSS, SCHEME_ATTRIBUTE } from "./stylesheet.js";
+import { useOverlayScheme } from "./theme.js";
+import { createElement, forwardRef, useEffect, useLayoutEffect, useMemo, useState } from "react";
+import { readMapleConfig } from "@maple-kit/core/client";
+import { createOverlayHost } from "@maple-kit/core/overlay";
+import { MapleProvider } from "@maple-kit/react";
+import { createPortal } from "react-dom";
+//#region src/root.ts
+const MapleRoot = forwardRef(function MapleRoot(props, ref) {
+	const [config] = useState(() => readMapleConfig(props));
+	const [shots] = useState(createShotStore);
+	const host = useOverlayHost(config.enabled, props.nonce, props.parent);
+	const options = useMemo(() => ({
+		...props.options,
+		branch: props.branch,
+		...props.label === void 0 ? {} : { label: props.label },
+		...props.commit === void 0 ? {} : { commit: props.commit },
+		config
+	}), [
+		props.options,
+		props.branch,
+		props.label,
+		props.commit,
+		config
+	]);
+	if (!host || !config.enabled) return null;
+	const className = props.className ? `mk-layer ${props.className}` : "mk-layer";
+	const layer = createElement("div", {
+		className,
+		ref
+	}, props.children);
+	const scoped = createElement(OverlayLayer, { host }, layer);
+	return createElement(MapleProvider, props.client ? { client: props.client } : { options }, createElement(ShotContext.Provider, { value: shots }, createPortal(scoped, host.root)));
+});
+function useOverlayHost(enabled, nonce, parent) {
+	const [host, setHost] = useState();
+	useEffect(() => {
+		if (!enabled) return;
+		const mounted = createOverlayHost({
+			...nonce === void 0 ? {} : { nonce },
+			...parent === void 0 ? {} : { parent }
+		});
+		mounted.addStyles(OVERLAY_CSS);
+		setHost(mounted);
+		return () => mounted.destroy();
+	}, [
+		enabled,
+		nonce,
+		parent
+	]);
+	return host;
+}
+function OverlayLayer(props) {
+	const theme = useOverlayScheme();
+	const { container, root } = props.host;
+	useLayoutEffect(() => {
+		container.setAttribute(SCHEME_ATTRIBUTE, theme.scheme);
+	}, [container, theme.scheme]);
+	const value = useMemo(() => ({
+		root,
+		container,
+		scheme: theme.scheme,
+		hostScheme: theme.hostScheme
+	}), [
+		root,
+		container,
+		theme.scheme,
+		theme.hostScheme
+	]);
+	return createElement(MapleUiContext.Provider, { value }, props.children);
+}
+//#endregion
+export { MapleRoot };

package/dist/shots.js

@@ -0,0 +1,32 @@
+import { createContext, useContext } from "react";
+//#region src/shots.ts
+function createShotStore() {
+	const listeners = /* @__PURE__ */ new Set();
+	let held;
+	const tell = () => {
+		for (const listener of listeners) listener();
+	};
+	return {
+		get: () => held,
+		put(shot) {
+			held = shot;
+			tell();
+		},
+		take() {
+			const shot = held;
+			held = void 0;
+			if (shot) tell();
+			return shot;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		}
+	};
+}
+const ShotContext = createContext(null);
+function useShots() {
+	return useContext(ShotContext);
+}
+//#endregion
+export { ShotContext, createShotStore, useShots };

package/dist/slot.d.ts

@@ -0,0 +1,28 @@
+import { HTMLAttributes, ReactNode, Ref } from "react";
+//#region src/slot.d.ts
+/** Props of unknown shape, which is what a caller's element has. */
+type AnyProps = Record<string, unknown>;
+/** Every part accepts this, and none of them accepts a visual variant. */
+export interface AsChildProps {
+  /** Render the single child instead of the part's own element. */
+  readonly asChild?: boolean;
+}
+/** What `<Slot>` renders into: the part's props, over one element child. */
+export interface SlotProps extends HTMLAttributes<HTMLElement> {
+  readonly children?: ReactNode;
+}
+/** Thrown when `asChild` was given something other than one element. */
+export declare class AsChildError extends Error {
+  readonly name = "AsChildError";
+  constructor();
+}
+/** Calls every ref it was given with the same node. */
+export declare function composeRefs<T>(...refs: readonly (Ref<T> | undefined)[]): (node: T | null) => void;
+/** The part's props first, the child's over them, merging the three that merge. */
+export declare function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps;
+/**
+ * Renders its one element child with the part's props merged in. Parts pick it
+ * with `const Element = asChild ? Slot : "button"` and change nothing else.
+ */
+export declare const Slot: import("react").ForwardRefExoticComponent<SlotProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion

package/dist/slot.js

@@ -0,0 +1,52 @@
+import { cloneElement, forwardRef, isValidElement } from "react";
+//#region src/slot.ts
+var AsChildError = class extends Error {
+	name = "AsChildError";
+	constructor() {
+		super("asChild needs exactly one React element as its child.");
+	}
+};
+function composeRefs(...refs) {
+	return (node) => {
+		for (const ref of refs) if (typeof ref === "function") ref(node);
+		else if (ref) ref.current = node;
+	};
+}
+function isHandler(key) {
+	return key.startsWith("on") && key.length > 2 && key[2] === key[2]?.toUpperCase();
+}
+function composeHandlers(slot, child) {
+	if (typeof slot !== "function" || typeof child !== "function") return child ?? slot;
+	return (...args) => {
+		slot(...args);
+		child(...args);
+	};
+}
+function mergeValue(key, slot, child) {
+	if (isHandler(key)) return composeHandlers(slot, child);
+	if (key === "className") return [slot, child].filter(Boolean).join(" ") || void 0;
+	if (key === "style") return {
+		...slot,
+		...child
+	};
+	return child ?? slot;
+}
+function mergeProps(slotProps, childProps) {
+	const merged = { ...slotProps };
+	for (const key of Object.keys(childProps)) merged[key] = mergeValue(key, slotProps[key], childProps[key]);
+	return merged;
+}
+function refOf(child) {
+	const onElement = child.ref;
+	return child.props["ref"] ?? onElement;
+}
+const Slot = forwardRef(function Slot(props, ref) {
+	const { children, ...slotProps } = props;
+	if (!isValidElement(children)) throw new AsChildError();
+	const child = children;
+	const merged = mergeProps(slotProps, child.props);
+	merged["ref"] = composeRefs(ref, refOf(child));
+	return cloneElement(child, merged);
+});
+//#endregion
+export { AsChildError, Slot, composeRefs, mergeProps };

package/dist/slots.d.ts

@@ -0,0 +1,24 @@
+//#region src/slots.d.ts
+/**
+ * The ten reviewer colours, and the only supported way to apply one.
+ *
+ * Hue is constant across schemes and lightness alternates between neighbours,
+ * so two adjacent slots stay apart under deuteranopia. A slot reaches an
+ * element as two custom properties set with `setProperty`; a generated rule per
+ * reviewer would grow the stylesheet with the team and break the CSP claim.
+ */
+/** How many slots there are. `CommentAuthor.colorSlot` is a number under this. */
+export declare const REVIEWER_SLOT_COUNT: number;
+/** The reviewer's colour. Out-of-range and negative slots wrap rather than throw. */
+export declare function slotColor(slot: number): string;
+/** What reads on top of {@link slotColor} at the same hue. */
+export declare function slotInk(slot: number): string;
+/** What `applyReviewerSlot` writes, and the only two runtime colour tokens. */
+export declare const SLOT_PROPERTY = "--mk-slot";
+export declare const SLOT_INK_PROPERTY = "--mk-slot-ink";
+/**
+ * Paints one element in a reviewer's colour. Two `setProperty` calls, never a
+ * rule and never `cssText`, which is the one CSSOM call CSP checks.
+ */
+export declare function applyReviewerSlot(element: ElementCSSInlineStyle, slot: number): void;
+//#endregion

package/dist/slots.js

@@ -0,0 +1,75 @@
+//#region src/slots.ts
+const PALETTE = [
+	{
+		l: .63,
+		c: .13,
+		h: 22
+	},
+	{
+		l: .77,
+		c: .12,
+		h: 62
+	},
+	{
+		l: .62,
+		c: .12,
+		h: 104
+	},
+	{
+		l: .76,
+		c: .11,
+		h: 146
+	},
+	{
+		l: .61,
+		c: .1,
+		h: 182
+	},
+	{
+		l: .75,
+		c: .1,
+		h: 214
+	},
+	{
+		l: .62,
+		c: .13,
+		h: 252
+	},
+	{
+		l: .76,
+		c: .11,
+		h: 288
+	},
+	{
+		l: .61,
+		c: .13,
+		h: 320
+	},
+	{
+		l: .75,
+		c: .12,
+		h: 350
+	}
+];
+const INK_ABOVE = .68;
+const REVIEWER_SLOT_COUNT = PALETTE.length;
+function at(slot) {
+	const index = (Math.trunc(slot) % PALETTE.length + PALETTE.length) % PALETTE.length;
+	return PALETTE[index] ?? PALETTE[0];
+}
+function slotColor(slot) {
+	const { l, c, h } = at(slot);
+	return `oklch(${l} ${c} ${h})`;
+}
+function slotInk(slot) {
+	const { l, h } = at(slot);
+	return l > INK_ABOVE ? `oklch(0.22 0.03 ${h})` : `oklch(0.99 0.01 ${h})`;
+}
+const SLOT_PROPERTY = "--mk-slot";
+const SLOT_INK_PROPERTY = "--mk-slot-ink";
+function applyReviewerSlot(element, slot) {
+	element.style.setProperty(SLOT_PROPERTY, slotColor(slot));
+	element.style.setProperty(SLOT_INK_PROPERTY, slotInk(slot));
+}
+//#endregion
+export { REVIEWER_SLOT_COUNT, SLOT_INK_PROPERTY, SLOT_PROPERTY, applyReviewerSlot, slotColor, slotInk };

package/dist/stylesheet.d.ts

@@ -0,0 +1,15 @@
+//#region src/stylesheet.d.ts
+/**
+ * The overlay's stylesheet: one string, built from the token table.
+ *
+ * It is a constant rather than a CSS file behind a loader, so it needs no
+ * bundler plugin, stays tree-shakeable, and leaves the CSP claim in
+ * docs/overlay-csp.md checkable by reading `buildOverlayCss` and
+ * `createOverlayStyleSheet`. Nothing here constructs a `CSSStyleSheet`, reaches
+ * `document` or reads storage; building a string does none of those.
+ */
+/** The attribute the root writes the overlay's resolved scheme to. */
+export declare const SCHEME_ATTRIBUTE = "data-mk-scheme";
+/** The overlay's styles. The only thing `Maple.Root` adopts. */
+export declare const OVERLAY_CSS: string;
+//#endregion