@c2n/copy-button 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nguyen Thai Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @c2n/copy-button
+
+Copy button built with Lit: puts text on the clipboard — the element it sits in, another element by `id`, or a literal string.
+
+```bash
+npm install @c2n/copy-button
+```
+
+```html
+<script type="module">
+  import '@c2n/copy-button'
+</script>
+
+<!-- Copies its parent, pinned in the corner, revealed on hover. -->
+<pre style="position: relative">npx -y @c2n/mcp<c2-copy-button pin></c2-copy-button></pre>
+
+<!-- Copies another element by id. -->
+<p id="address">548 Market St, San Francisco, CA 94104</p>
+<c2-copy-button for="address" reveal="always">Copy address</c2-copy-button>
+
+<!-- Copies an exact string. -->
+<c2-copy-button value="c2n_live_8f4c19ab7e2d" reveal="always">Copy token</c2-copy-button>
+```
+
+- **Source**: `value` (a literal string) wins, then `for` (the `id` of the source element, looked up in the containing document or shadow root), then the light-DOM parent. `parentElement` is deliberate: a button slotted into another custom element copies the element it was authored inside, not the shadow-DOM node it renders in.
+- **Reading a source**: each source is read the way it stores its text — the `source` of a `c2-code-viewer` (the real code, not the highlighted token spans), the `value` of an `<input>`, `<textarea>` or `<select>`, and the rendered text of anything else. Any `c2-copy-button` inside the source is skipped, so a button sitting in the block it copies never copies its own label. Inner whitespace is preserved (newlines in a `<pre>` survive); only the leading and trailing whitespace is trimmed.
+- **Reveal**: `reveal="hover"` is the default — the button is transparent until the pointer enters its source, so a corner button does not sit on top of the content it copies. Only the opacity changes, so it keeps its box and stays reachable: it also appears when focus lands anywhere inside the source, on devices with no hover at all (where a hover-only button would be unreachable), and for as long as the `copied` confirmation shows. While hidden it takes no pointer events, so there is never an invisible click target. `reveal="always"` shows it permanently.
+- **Pin**: `pin` absolutely positions the button in a corner of its containing block — the bare attribute means top right, or name one of `top-right`, `top-left`, `bottom-right`, `bottom-left` — inset by `--c2-copy-button__pin--offset-x` / `-y`. Give the element it sits in `position: relative`, as with any absolutely positioned child. A pinned button also **stays put while its source scrolls**: an absolutely positioned child of a scrolling box lives in that box's scrollable overflow and would otherwise scroll away with the content, exactly when it is needed, since long or wide text is why there is a scrollbar at all. It finds the nearest ancestor that can scroll and cancels out its scroll offset, in both directions. The lookup is keyed on the overflow style rather than on whether the box currently overflows, so content that grows later (a webfont finishing) cannot leave the button attached to nothing.
+- **Feedback**: after a successful copy the icon becomes a check and the `copied` attribute is set for `copied-duration` ms (default `2000`), then cleared. `copied` is reflected, so `c2-copy-button[copied]` is styleable from outside, and the `__container__copied--*` variables cover it from within.
+- **Events**: `copied` carries `detail.text`; `copy-error` carries `detail.error` when the clipboard write is refused, so a failure is never silent. The async `copy()` method returns `false` in that case.
+- **Slots**: the default slot is an optional label beside the icon — leave it empty for an icon-only, square button. `copy-icon` and `copied-icon` replace the two glyphs; `copied-label` replaces the text while the copied state shows.
+- **Accessibility**: renders a real `<button>` with focus delegated to it. The accessible name comes from `label` / `copied-label` (default "Copy" / "Copied"), and the state change is announced through a visually hidden `role="status"` region, because an icon swap alone is not read out.
+- **Fallback**: where `navigator.clipboard` is unavailable — any non-secure context, which includes a plain-http dev server — it falls back to an off-screen `<textarea>` and `document.execCommand('copy')` rather than doing nothing.
+
+Everything is themed through CSS custom properties: `__container--*` for the button box (size, padding, radius, border, colours, typography) with `__hover`, `__active`, `__focus`, `__disabled` and `__copied` states, `__icon--*` for the glyph, `__pin--offset-x` / `-y` for the pinned inset and `--c2-copy-button--transition-duration` for the reveal fade. The full list is in `custom-elements.json` and on the docs site.

package/dist/copy-button.js

@@ -0,0 +1,367 @@
+import { LitElement, html, nothing, unsafeCSS } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+//#region src/copy-button.scss?inline
+var copy_button_default = "/* ex : var((width: 24px), width, c2-checkbox)  returns var(--c2-checkbox-width, 24px) */\n:host {\n  display: inline-flex;\n}\n\n:host([hidden]) {\n  display: none;\n}\n\n:host([pin]) {\n  position: absolute;\n  top: var(--c2-copy-button__pin--offset-y,6px);\n  right: var(--c2-copy-button__pin--offset-x,6px);\n  transform: translate(var(--_c2-copy-button-scroll-x, 0px), var(--_c2-copy-button-scroll-y, 0px));\n}\n\n:host([pin=top-left]) {\n  right: auto;\n  left: var(--c2-copy-button__pin--offset-x,6px);\n}\n\n:host([pin=bottom-right]) {\n  top: auto;\n  bottom: var(--c2-copy-button__pin--offset-y,6px);\n}\n\n:host([pin=bottom-left]) {\n  top: auto;\n  bottom: var(--c2-copy-button__pin--offset-y,6px);\n  right: auto;\n  left: var(--c2-copy-button__pin--offset-x,6px);\n}\n\n:host([disabled]) {\n  pointer-events: none;\n  opacity: var(--c2-copy-button__container__disabled--opacity,0.38);\n}\n\n.c2-copy-button {\n  appearance: none;\n  box-sizing: border-box;\n  margin: 0;\n  font: inherit;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: var(--c2-copy-button__container--gap,6px);\n  height: var(--c2-copy-button__container--height,28px);\n  min-width: var(--c2-copy-button__container--min-width,28px);\n  padding: 0 var(--c2-copy-button__container--padding-right,6px) 0 var(--c2-copy-button__container--padding-left,6px);\n  border: var(--c2-copy-button__container--border,none);\n  border-radius: var(--c2-copy-button__container--border-radius,6px);\n  background-color: var(--c2-copy-button__container--background-color);\n  color: var(--c2-copy-button__container--color,rgb(34, 34, 34));\n  font-size: var(--c2-copy-button__container--font-size,12px);\n  font-weight: var(--c2-copy-button__container--font-weight,500);\n  font-family: var(--c2-copy-button__container--font-family);\n  cursor: pointer;\n  user-select: none;\n  transition: background-color 250ms cubic-bezier(0.2, 0, 0, 1), color 250ms cubic-bezier(0.2, 0, 0, 1);\n}\n.c2-copy-button:hover {\n  background-color: var(--c2-copy-button__container__hover--background-color,rgb(230, 230, 230));\n  color: var(--c2-copy-button__container__hover--color,var(--c2-copy-button__container--color,rgb(34, 34, 34)));\n  border: var(--c2-copy-button__container__hover--border,var(--c2-copy-button__container--border,none));\n}\n.c2-copy-button:active {\n  background-color: var(--c2-copy-button__container__active--background-color,var(--c2-copy-button__container__hover--background-color,rgb(213, 213, 213)));\n}\n.c2-copy-button:focus-visible {\n  outline: var(--c2-copy-button__container__focus--outline,2px solid rgba(2, 101, 220, 0.4));\n  outline-offset: var(--c2-copy-button__container__focus--outline-offset,2px);\n}\n.c2-copy-button:disabled {\n  cursor: default;\n}\n.c2-copy-button.is-copied {\n  color: var(--c2-copy-button__container__copied--color,rgb(0, 122, 77));\n  background-color: var(--c2-copy-button__container__copied--background-color,var(--c2-copy-button__container--background-color));\n  border: var(--c2-copy-button__container__copied--border,var(--c2-copy-button__container--border,none));\n}\n.c2-copy-button.is-failed {\n  color: rgb(211, 21, 16);\n}\n\n:host(:not([reveal=always])) .c2-copy-button {\n  opacity: 0;\n  pointer-events: none;\n  transition: opacity var(--c2-copy-button--transition-duration,150ms) cubic-bezier(0.2, 0, 0, 1);\n}\n\n:host(:not([reveal=always])) .c2-copy-button.is-visible {\n  opacity: 1;\n  pointer-events: auto;\n}\n\n@media (prefers-reduced-motion: reduce) {\n  :host(:not([reveal=always])) .c2-copy-button {\n    transition: none;\n  }\n}\n.c2-copy-button-icon {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex: none;\n  width: var(--c2-copy-button__icon--size,16px);\n  height: var(--c2-copy-button__icon--size,16px);\n  color: var(--c2-copy-button__icon--color);\n  transition: color 250ms cubic-bezier(0.2, 0, 0, 1);\n}\n.c2-copy-button-icon svg,\n.c2-copy-button-icon ::slotted(*) {\n  width: 100%;\n  height: 100%;\n  --c2-feather-icon--size: var(--c2-copy-button__icon--size,16px);\n  --c2-mat-icon--font-size: var(--c2-copy-button__icon--size,16px);\n}\n\n.c2-copy-button.is-copied .c2-copy-button-icon {\n  color: var(--c2-copy-button__icon__copied--color,var(--c2-copy-button__container__copied--color,rgb(0, 122, 77)));\n}\n\n.c2-copy-button-label {\n  display: contents;\n  white-space: nowrap;\n}\n\n.c2-copy-button-status {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  margin: -1px;\n  padding: 0;\n  overflow: hidden;\n  clip-path: inset(50%);\n  white-space: nowrap;\n  border: 0;\n}";
+//#endregion
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/copy-button.ts
+/** Elements that carry their text on a property rather than in their child nodes. */
+var TEXT_PROPERTY_TAGS = [
+	"input",
+	"textarea",
+	"select"
+];
+var SCROLLABLE_OVERFLOW = [
+	"auto",
+	"scroll",
+	"overlay"
+];
+var CopyButton = class CopyButton extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.value = void 0;
+		this.for = void 0;
+		this.disabled = false;
+		this.copied = false;
+		this.copiedDuration = 2e3;
+		this.label = "Copy";
+		this.copiedLabel = "Copied";
+		this.reveal = "hover";
+		this.pin = void 0;
+		this.failed = false;
+		this.hovered = false;
+		this.focused = false;
+		this.hoverTarget = null;
+		this.scroller = null;
+		this.scrollFrame = 0;
+		this.handleHoverQueryChange = () => this.requestUpdate();
+		this.handlePointerEnter = () => this.updateReveal(() => this.hovered = true);
+		this.handlePointerLeave = () => this.updateReveal(() => this.hovered = false);
+		this.handleFocusIn = () => this.updateReveal(() => this.focused = deepActiveElement()?.matches(":focus-visible") ?? false);
+		this.handleFocusOut = (event) => this.updateReveal(() => {
+			const next = event.relatedTarget;
+			if (next instanceof Node && this.hoverTarget?.contains(next)) return;
+			this.focused = false;
+		});
+		this.handleScroll = () => {
+			cancelAnimationFrame(this.scrollFrame);
+			this.scrollFrame = requestAnimationFrame(() => this.syncPinOffset());
+		};
+	}
+	static {
+		this.styles = unsafeCSS(copy_button_default);
+	}
+	static {
+		this.shadowRootOptions = {
+			...LitElement.shadowRootOptions,
+			delegatesFocus: true
+		};
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		this.hoverQuery ??= window.matchMedia?.("(hover: hover)");
+		this.hoverQuery?.addEventListener("change", this.handleHoverQueryChange);
+	}
+	disconnectedCallback() {
+		super.disconnectedCallback();
+		clearTimeout(this.timer);
+		cancelAnimationFrame(this.scrollFrame);
+		this.hoverQuery?.removeEventListener("change", this.handleHoverQueryChange);
+		this.detachHoverTarget();
+		this.detachScroller();
+	}
+	firstUpdated() {
+		this.attachHoverTarget();
+		this.attachScroller();
+	}
+	willUpdate(changed) {
+		if (changed.has("for") && this.hasUpdated) this.attachHoverTarget();
+		if (changed.has("pin") && this.hasUpdated) this.attachScroller();
+	}
+	/** True when the button should be visible: `always`, no hover support, or the user is actually there. */
+	get isVisible() {
+		if (this.reveal === "always") return true;
+		if (this.hoverQuery && !this.hoverQuery.matches) return true;
+		return this.hovered || this.focused;
+	}
+	/**
+	* Resolved fade duration of the reveal transition, in ms.
+	*
+	* Read off the rendered button rather than off the custom property, so an overridden
+	* `--c2-copy-button--transition-duration` and `prefers-reduced-motion: reduce` (which drops it to `0s`) are both
+	* accounted for without re-deriving the cascade here.
+	*/
+	get concealDuration() {
+		const button = this.renderRoot?.querySelector("button");
+		if (!button) return 0;
+		const [first = ""] = getComputedStyle(button).transitionDuration.split(",");
+		const value = Number.parseFloat(first);
+		if (!Number.isFinite(value)) return 0;
+		return first.trim().endsWith("ms") ? value : value * 1e3;
+	}
+	attachHoverTarget() {
+		const next = this.sourceElement;
+		if (next === this.hoverTarget) return;
+		this.detachHoverTarget();
+		this.hoverTarget = next;
+		if (!next) return;
+		next.addEventListener("pointerenter", this.handlePointerEnter);
+		next.addEventListener("pointerleave", this.handlePointerLeave);
+		next.addEventListener("focusin", this.handleFocusIn);
+		next.addEventListener("focusout", this.handleFocusOut);
+	}
+	detachHoverTarget() {
+		const target = this.hoverTarget;
+		if (!target) return;
+		target.removeEventListener("pointerenter", this.handlePointerEnter);
+		target.removeEventListener("pointerleave", this.handlePointerLeave);
+		target.removeEventListener("focusin", this.handleFocusIn);
+		target.removeEventListener("focusout", this.handleFocusOut);
+		this.hoverTarget = null;
+	}
+	/** Applies a reveal change, re-arming the confirmation timer when the button crosses the visibility line. */
+	updateReveal(apply) {
+		const wasVisible = this.isVisible;
+		apply();
+		if (this.isVisible !== wasVisible) this.armResolvedTimer();
+	}
+	/**
+	* (Re)arms the reset of the `copied` / `failed` state.
+	*
+	* On screen it runs for the full `copied-duration`. Off screen it only has to outlast the fade: the state is
+	* cleared once the button is invisible, so the icon swap is never painted. Coming back mid-confirmation restarts
+	* the full countdown, so the state can never stick with no timer behind it.
+	*/
+	armResolvedTimer() {
+		if (!this.copied && !this.failed) return;
+		clearTimeout(this.timer);
+		this.timer = setTimeout(() => this.clearResolvedState(), this.isVisible ? this.copiedDuration : this.concealDuration);
+	}
+	clearResolvedState() {
+		this.copied = false;
+		this.failed = false;
+	}
+	attachScroller() {
+		this.detachScroller();
+		if (!this.pin && this.pin !== "") return;
+		this.scroller = nearestScrollable(this);
+		this.scroller?.addEventListener("scroll", this.handleScroll, { passive: true });
+		this.syncPinOffset();
+	}
+	detachScroller() {
+		this.scroller?.removeEventListener("scroll", this.handleScroll);
+		this.scroller = null;
+		this.style.removeProperty("--_c2-copy-button-scroll-x");
+		this.style.removeProperty("--_c2-copy-button-scroll-y");
+	}
+	/**
+	* Cancels out the scroll offset of the container.
+	*
+	* A pinned button is an absolutely positioned child of the scroll container, which puts it in the container's
+	* scrollable overflow — so it scrolls away with the content, exactly when the user needs it (long or wide text is
+	* the reason there is a scrollbar at all). Translating by the scroll offset holds it against the visible box.
+	* The same sign works for all four corners: `right`/`bottom` are resolved against the padding box, whose size is
+	* the client size, so every corner needs to move *with* the scroll.
+	*/
+	syncPinOffset() {
+		const scroller = this.scroller;
+		if (!scroller) return;
+		this.style.setProperty("--_c2-copy-button-scroll-x", `${scroller.scrollLeft}px`);
+		this.style.setProperty("--_c2-copy-button-scroll-y", `${scroller.scrollTop}px`);
+	}
+	/**
+	* The element the text is read from: `for` by id, else the light-DOM parent.
+	*
+	* `parentElement` is deliberate — a button slotted into another custom element should copy the element it was
+	* authored inside, not whatever shadow-DOM node it happens to be rendered in.
+	*/
+	get sourceElement() {
+		if (this.for) return this.getRootNode().querySelector?.(`#${CSS.escape(this.for)}`) ?? null;
+		return this.parentElement;
+	}
+	/** The text that would be copied right now. */
+	get text() {
+		if (this.value !== void 0) return this.value;
+		const source = this.sourceElement;
+		if (!source) return "";
+		return readText(source).trim();
+	}
+	/** Copies `text` to the clipboard and enters the `copied` state. Returns false when the write failed. */
+	async copy() {
+		const text = this.text;
+		try {
+			await writeToClipboard(text);
+		} catch (error) {
+			this.copied = false;
+			this.failed = true;
+			this.armResolvedTimer();
+			this.dispatchEvent(new CustomEvent("copy-error", {
+				detail: { error },
+				bubbles: true,
+				composed: true
+			}));
+			return false;
+		}
+		this.failed = false;
+		this.copied = true;
+		this.armResolvedTimer();
+		this.dispatchEvent(new CustomEvent("copied", {
+			detail: { text },
+			bubbles: true,
+			composed: true
+		}));
+		return true;
+	}
+	handleClick() {
+		this.copy();
+	}
+	renderIcon() {
+		if (this.copied) return html`<slot name="copied-icon"
+        ><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+          <polyline points="20 6 9 17 4 12"></polyline></svg
+      ></slot>`;
+		return html`<slot name="copy-icon"
+      ><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+        <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+        <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path></svg
+    ></slot>`;
+	}
+	render() {
+		return html`
+      <button
+        class=${classMap({
+			"c2-copy-button": true,
+			"is-copied": this.copied,
+			"is-failed": this.failed,
+			"is-visible": this.isVisible
+		})}
+        part="button"
+        type="button"
+        ?disabled=${this.disabled}
+        aria-label=${this.copied ? this.copiedLabel : this.label}
+        @click=${this.handleClick}
+      >
+        <span class="c2-copy-button-icon" part="icon">${this.renderIcon()}</span>
+        <span class="c2-copy-button-label"> ${this.copied ? html`<slot name="copied-label"><slot></slot></slot>` : html`<slot></slot>`} </span>
+      </button>
+      ${html`<span class="c2-copy-button-status" role="status" aria-live="polite"
+          >${this.copied ? this.copiedLabel : this.failed ? "Copy failed" : nothing}</span
+        >`}
+    `;
+	}
+};
+__decorate([property()], CopyButton.prototype, "value", void 0);
+__decorate([property()], CopyButton.prototype, "for", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CopyButton.prototype, "disabled", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true
+})], CopyButton.prototype, "copied", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "copied-duration"
+})], CopyButton.prototype, "copiedDuration", void 0);
+__decorate([property()], CopyButton.prototype, "label", void 0);
+__decorate([property({ attribute: "copied-label" })], CopyButton.prototype, "copiedLabel", void 0);
+__decorate([property({ reflect: true })], CopyButton.prototype, "reveal", void 0);
+__decorate([property({ reflect: true })], CopyButton.prototype, "pin", void 0);
+__decorate([state()], CopyButton.prototype, "failed", void 0);
+__decorate([state()], CopyButton.prototype, "hovered", void 0);
+__decorate([state()], CopyButton.prototype, "focused", void 0);
+CopyButton = __decorate([customElement("c2-copy-button")], CopyButton);
+/**
+* The focused element, descending through shadow roots.
+*
+* `document.activeElement` stops at the outermost shadow host, which for a focused copy button is the
+* `c2-copy-button` element itself — and a host never matches `:focus-visible` the way the inner `<button>` does.
+*/
+function deepActiveElement() {
+	let active = document.activeElement;
+	while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+	return active;
+}
+/**
+* The nearest ancestor that can scroll, starting at the button's parent.
+*
+* Deliberately keyed on the overflow *style* and not on whether the box currently overflows: this runs once on
+* first render, and content that grows later (a webfont finishing, a value being set) would otherwise leave the
+* button attached to nothing and scrolling away. A container that never overflows keeps `scrollTop`/`scrollLeft`
+* at 0, so compensating it costs nothing.
+*/
+function nearestScrollable(from) {
+	let element = from.parentElement;
+	while (element && element !== document.body && element !== document.documentElement) {
+		const style = getComputedStyle(element);
+		if (SCROLLABLE_OVERFLOW.includes(style.overflowY) || SCROLLABLE_OVERFLOW.includes(style.overflowX)) return element;
+		element = element.parentElement;
+	}
+	return null;
+}
+/**
+* Reads the text of a source element the way that element stores it.
+*
+* `c2-code-viewer` keeps the real (dedented) code on `source`, form fields keep it on `value`, and everything else
+* keeps it in its child nodes. Falling back to `textContent` for a code viewer would copy the syntax-highlighted
+* DOM, which is the same characters but assembled from dozens of token spans — and for a field it would copy nothing.
+*/
+function readText(element) {
+	if (TEXT_PROPERTY_TAGS.includes(element.localName)) return element.value ?? "";
+	const source = element.source;
+	if (typeof source === "string") return source;
+	const text = textExcludingCopyButtons(element);
+	if (text.trim()) return text;
+	const value = element.value;
+	return typeof value === "string" ? value : text;
+}
+/**
+* `textContent` of `element`, minus any `c2-copy-button` inside it.
+*
+* Without this, the common case in the component's own docstring — a button dropped inside the block it copies —
+* would copy the button's own label along with the content.
+*/
+function textExcludingCopyButtons(element) {
+	let text = "";
+	for (const node of element.childNodes) if (node.nodeType === Node.TEXT_NODE) text += node.nodeValue ?? "";
+	else if (node.nodeType === Node.ELEMENT_NODE) {
+		const child = node;
+		if (child.localName === "c2-copy-button") continue;
+		text += textExcludingCopyButtons(child);
+	}
+	return text;
+}
+/**
+* Writes to the clipboard, falling back to a hidden `<textarea>` + `execCommand` when the async Clipboard API is
+* unavailable. That covers non-secure contexts, which includes plain-http dev servers and previews — where
+* `navigator.clipboard` is simply undefined and the button would otherwise never work.
+*/
+async function writeToClipboard(text) {
+	if (navigator.clipboard?.writeText) {
+		await navigator.clipboard.writeText(text);
+		return;
+	}
+	const area = document.createElement("textarea");
+	area.value = text;
+	area.setAttribute("readonly", "");
+	area.setAttribute("aria-hidden", "true");
+	area.style.cssText = "position:fixed;top:0;left:-9999px;opacity:0";
+	document.body.append(area);
+	try {
+		area.select();
+		if (!document.execCommand("copy")) throw new Error("Copying to the clipboard is not available");
+	} finally {
+		area.remove();
+	}
+}
+//#endregion
+export { CopyButton };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@c2n/copy-button",
+  "version": "0.0.6",
+  "type": "module",
+  "main": "dist/copy-button.js",
+  "exports": {
+    ".": {
+      "default": "./dist/copy-button.js",
+      "types": "./types/src/copy-button.d.ts"
+    },
+    "./custom-elements.json": "./custom-elements.json"
+  },
+  "files": [
+    "dist",
+    "types"
+  ],
+  "keywords": [
+    "copy-button",
+    "web component",
+    "lit"
+  ],
+  "license": "MIT",
+  "author": "code2nguyen@gmail.com",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/code2nguyen/web-components.git"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "wireit",
+    "build:only": "vite build",
+    "type-check": "wireit"
+  },
+  "wireit": {
+    "type-check": {
+      "dependencies": [
+        "../../core:build"
+      ],
+      "command": "tsc -p tsconfig.lib.json --composite false"
+    },
+    "build": {
+      "dependencies": [
+        "type-check"
+      ],
+      "command": "vite build"
+    }
+  },
+  "dependencies": {
+    "@c2n/core": "0.0.6",
+    "lit": "3.3.3"
+  },
+  "devDependencies": {
+    "@c2n/config": "*"
+  },
+  "customElements": "custom-elements.json",
+  "gitHead": "2921054bc75299da66dad11c1e374246ff88a51e"
+}

package/types/src/copy-button.d.ts

@@ -0,0 +1,193 @@
+import { LitElement, type PropertyValues } from 'lit';
+/** Corners `pin` can anchor to. The bare `pin` attribute means `top-right`. */
+export type CopyButtonPin = 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
+/**
+ * Copies text to the clipboard.
+ *
+ * Drop it inside the element you want to copy and it copies that element: `<pre><c2-copy-button></c2-copy-button>…</pre>`
+ * copies the `<pre>`. Point it somewhere else with `for` (the `id` of the source), or give it the literal text with
+ * `value`. It reads the source the way that source stores its text — the `source` of a `c2-code-viewer`, the `value`
+ * of an `<input>`/`<textarea>` or of a field that keeps its input in a shadow root (`c2-text-field`), otherwise the
+ * rendered text — and never copies its own label, so a button sitting inside its source does not end up in the result.
+ *
+ * Renders a real `<button>` (focus is delegated to it). With no content it is an icon-only button; slot text to get
+ * an icon and a label. After a successful copy it flips to the `copied` state for `copied-duration` ms.
+ *
+ * By default it only appears while the pointer is over its source (`reveal="always"` opts out), and `pin` puts it in
+ * a corner of the source where it stays put even while the source scrolls.
+ *
+ * @tag c2-copy-button
+ *
+ * @slot - Optional label beside the icon. Empty by default, which gives an icon-only button.
+ * @slot copy-icon - Replaces the default copy icon.
+ * @slot copied-icon - Replaces the default check icon shown after a copy.
+ * @slot copied-label - Replaces the default slot's text while in the `copied` state.
+ *
+ * @event {CustomEvent<{ text: string }>} copied - Fired after the text reached the clipboard. `detail.text` is what was copied.
+ * @event {CustomEvent<{ error: unknown }>} copy-error - Fired when the clipboard write failed (denied permission, or no clipboard at all).
+ *
+ * @cssproperty {color} --c2-copy-button__container--background-color
+ * @cssproperty {color} [--c2-copy-button__container--color=rgb(34, 34, 34)]
+ * @cssproperty {border} [--c2-copy-button__container--border=none]
+ * @cssproperty {border-radius} [--c2-copy-button__container--border-radius=6px]
+ * @cssproperty {pixel} [--c2-copy-button__container--height=28px]
+ * @cssproperty {pixel} [--c2-copy-button__container--min-width=28px]
+ * @cssproperty {padding} [--c2-copy-button__container--padding-left=6px]
+ * @cssproperty {padding} [--c2-copy-button__container--padding-right=6px]
+ * @cssproperty {pixel} [--c2-copy-button__container--gap=6px]
+ * @cssproperty {font-size} [--c2-copy-button__container--font-size=12px]
+ * @cssproperty {font-weight} [--c2-copy-button__container--font-weight=500]
+ * @cssproperty {font-family} --c2-copy-button__container--font-family
+ *
+ * @cssproperty {color} [--c2-copy-button__container__hover--background-color=rgb(230, 230, 230)]
+ * @cssproperty {color} --c2-copy-button__container__hover--color
+ * @cssproperty {border} --c2-copy-button__container__hover--border
+ * @cssproperty {color} [--c2-copy-button__container__active--background-color=rgb(213, 213, 213)]
+ * @cssproperty {outline} [--c2-copy-button__container__focus--outline=2px solid rgba(2, 101, 220, 0.4)]
+ * @cssproperty {pixel} [--c2-copy-button__container__focus--outline-offset=2px]
+ * @cssproperty {opacity} [--c2-copy-button__container__disabled--opacity=0.38]
+ *
+ * @cssproperty {color} [--c2-copy-button__container__copied--color=rgb(0, 122, 77)] - Applied for `copied-duration` after a successful copy.
+ * @cssproperty {color} --c2-copy-button__container__copied--background-color
+ * @cssproperty {border} --c2-copy-button__container__copied--border
+ *
+ * @cssproperty {pixel} [--c2-copy-button__icon--size=16px]
+ * @cssproperty {color} --c2-copy-button__icon--color - Defaults to the button's text colour.
+ * @cssproperty {color} --c2-copy-button__icon__copied--color
+ *
+ * @cssproperty {time} [--c2-copy-button--transition-duration=150ms] - Fade of the hover reveal.
+ * @cssproperty {pixel} [--c2-copy-button__pin--offset-x=6px] - Inset from the pinned corner, horizontally.
+ * @cssproperty {pixel} [--c2-copy-button__pin--offset-y=6px] - Inset from the pinned corner, vertically.
+ */
+export declare class CopyButton extends LitElement {
+    static styles: import("lit").CSSResult;
+    static shadowRootOptions: {
+        delegatesFocus: boolean;
+        clonable?: boolean;
+        customElementRegistry?: CustomElementRegistry | null;
+        mode: ShadowRootMode;
+        serializable?: boolean;
+        slotAssignment?: SlotAssignmentMode;
+    };
+    /** Literal text to copy. Takes precedence over `for` and over the parent element. */
+    value: string | undefined;
+    /** `id` of the element to copy, looked up in the containing document or shadow root. Overrides the parent element. */
+    for: string | undefined;
+    /** Disables the button: no pointer events, no focus, reduced opacity. */
+    disabled: boolean;
+    /** True for `copied-duration` after a successful copy. Reflected, so `c2-copy-button[copied]` is styleable. */
+    copied: boolean;
+    /** How long the `copied` state lasts, in ms. */
+    copiedDuration: number;
+    /** Accessible name of the button while idle. */
+    label: string;
+    /** Accessible name (and `copied-label` fallback) after a successful copy. */
+    copiedLabel: string;
+    /**
+     * `hover` (default) keeps the button transparent until the pointer is over its source, or keyboard focus lands
+     * inside it. `always` shows it permanently. A hover-only button still appears on keyboard focus and on devices
+     * with no hover at all.
+     *
+     * The `copied` confirmation deliberately does *not* hold it on screen: once the pointer leaves, the button fades
+     * out with the check still on it and resets off-screen, so the icon never flips back to `copy` on a button the
+     * user has already walked away from.
+     */
+    reveal: 'hover' | 'always';
+    /**
+     * Pins the button to a corner of its containing block, staying put while the source scrolls under it.
+     *
+     * The bare attribute means `top-right`. The containing block must be positioned (`position: relative` on the
+     * element the button sits in), as with any absolutely positioned child.
+     */
+    pin: CopyButtonPin | '' | undefined;
+    /** Set when the last copy attempt failed, so the failure is visible rather than silent. */
+    private failed;
+    /** Whether the pointer is currently over the source. */
+    private hovered;
+    /** Whether the source holds *keyboard* focus. Mouse focus does not count — see `handleFocusIn`. */
+    private focused;
+    private timer;
+    /** The element whose hover reveals the button, and whose keyboard focus keeps it revealed. */
+    private hoverTarget;
+    /** The scroll container whose offset the pin compensates for. */
+    private scroller;
+    private scrollFrame;
+    /**
+     * Devices without hover (touch) never fire `pointerenter`, so a hover-only button would be unreachable there.
+     * `matchMedia` is read once per instance and kept live, because a hybrid device can gain or lose a pointer.
+     */
+    private hoverQuery;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    firstUpdated(): void;
+    willUpdate(changed: PropertyValues<this>): void;
+    private handleHoverQueryChange;
+    /** True when the button should be visible: `always`, no hover support, or the user is actually there. */
+    private get isVisible();
+    /**
+     * Resolved fade duration of the reveal transition, in ms.
+     *
+     * Read off the rendered button rather than off the custom property, so an overridden
+     * `--c2-copy-button--transition-duration` and `prefers-reduced-motion: reduce` (which drops it to `0s`) are both
+     * accounted for without re-deriving the cascade here.
+     */
+    private get concealDuration();
+    private attachHoverTarget;
+    private detachHoverTarget;
+    private handlePointerEnter;
+    private handlePointerLeave;
+    /**
+     * Only *keyboard* focus holds a hover-reveal button on screen.
+     *
+     * A mouse click focuses the button too, so counting every `focusin` as a reveal kept an abandoned button fully
+     * opaque after the pointer had left — long enough for the confirmation to expire and flip the icon back to
+     * `copy` in place, which reads as a phantom second interaction. `:focus-visible` is exactly the distinction the
+     * platform already draws, so it is read off the focused element instead of being guessed at.
+     */
+    private handleFocusIn;
+    private handleFocusOut;
+    /** Applies a reveal change, re-arming the confirmation timer when the button crosses the visibility line. */
+    private updateReveal;
+    /**
+     * (Re)arms the reset of the `copied` / `failed` state.
+     *
+     * On screen it runs for the full `copied-duration`. Off screen it only has to outlast the fade: the state is
+     * cleared once the button is invisible, so the icon swap is never painted. Coming back mid-confirmation restarts
+     * the full countdown, so the state can never stick with no timer behind it.
+     */
+    private armResolvedTimer;
+    private clearResolvedState;
+    private attachScroller;
+    private detachScroller;
+    private handleScroll;
+    /**
+     * Cancels out the scroll offset of the container.
+     *
+     * A pinned button is an absolutely positioned child of the scroll container, which puts it in the container's
+     * scrollable overflow — so it scrolls away with the content, exactly when the user needs it (long or wide text is
+     * the reason there is a scrollbar at all). Translating by the scroll offset holds it against the visible box.
+     * The same sign works for all four corners: `right`/`bottom` are resolved against the padding box, whose size is
+     * the client size, so every corner needs to move *with* the scroll.
+     */
+    private syncPinOffset;
+    /**
+     * The element the text is read from: `for` by id, else the light-DOM parent.
+     *
+     * `parentElement` is deliberate — a button slotted into another custom element should copy the element it was
+     * authored inside, not whatever shadow-DOM node it happens to be rendered in.
+     */
+    get sourceElement(): HTMLElement | null;
+    /** The text that would be copied right now. */
+    get text(): string;
+    /** Copies `text` to the clipboard and enters the `copied` state. Returns false when the write failed. */
+    copy(): Promise<boolean>;
+    private handleClick;
+    private renderIcon;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'c2-copy-button': CopyButton;
+    }
+}
+//# sourceMappingURL=copy-button.d.ts.map

package/types/src/copy-button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-button.d.ts","sourceRoot":"","sources":["../../src/copy-button.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA4B,KAAK,cAAc,EAAE,MAAM,KAAK,CAAA;AAQ/E,+EAA+E;AAC/E,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,UAAU,GAAG,cAAc,GAAG,aAAa,CAAA;AAIrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,qBACa,UAAW,SAAQ,UAAU;IACxC,OAAgB,MAAM,0BAAoB;IAE1C,OAAgB,iBAAiB;;;;;;;MAA4D;IAE7F,qFAAqF;IACzE,KAAK,EAAE,MAAM,GAAG,SAAS,CAAY;IAEjD,sHAAsH;IAC1G,GAAG,EAAE,MAAM,GAAG,SAAS,CAAY;IAE/C,yEAAyE;IAC7B,QAAQ,UAAQ;IAE5D,+GAA+G;IACnE,MAAM,UAAQ;IAE1D,gDAAgD;IACU,cAAc,SAAO;IAE/E,gDAAgD;IACpC,KAAK,SAAS;IAE1B,6EAA6E;IACpC,WAAW,SAAW;IAE/D;;;;;;;;OAQG;IAC0B,MAAM,EAAE,OAAO,GAAG,QAAQ,CAAU;IAEjE;;;;;OAKG;IAC0B,GAAG,EAAE,aAAa,GAAG,EAAE,GAAG,SAAS,CAAY;IAE5E,2FAA2F;IAClF,OAAO,CAAC,MAAM,CAAQ;IAE/B,wDAAwD;IAC/C,OAAO,CAAC,OAAO,CAAQ;IAEhC,mGAAmG;IAC1F,OAAO,CAAC,OAAO,CAAQ;IAEhC,OAAO,CAAC,KAAK,CAA2C;IAExD,8FAA8F;IAC9F,OAAO,CAAC,WAAW,CAA2B;IAE9C,iEAAiE;IACjE,OAAO,CAAC,QAAQ,CAA2B;IAE3C,OAAO,CAAC,WAAW,CAAI;IAEvB;;;OAGG;IACH,OAAO,CAAC,UAAU,CAA4B;IAErC,iBAAiB;IAMjB,oBAAoB;IASpB,YAAY;IAKZ,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAMjD,OAAO,CAAC,sBAAsB,CAA6B;IAE3D,yGAAyG;IACzG,OAAO,KAAK,SAAS,GAIpB;IAED;;;;;;OAMG;IACH,OAAO,KAAK,eAAe,GAO1B;IAMD,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,kBAAkB,CAAuD;IACjF,OAAO,CAAC,kBAAkB,CAAwD;IAElF;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa,CAA0G;IAE/H,OAAO,CAAC,cAAc,CAMlB;IAEJ,6GAA6G;IAC7G,OAAO,CAAC,YAAY;IAMpB;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,YAAY,CAGnB;IAED;;;;;;;;OAQG;IACH,OAAO,CAAC,aAAa;IAOrB;;;;;OAKG;IACH,IAAI,aAAa,IAAI,WAAW,GAAG,IAAI,CAMtC;IAED,+CAA+C;IAC/C,IAAI,IAAI,IAAI,MAAM,CAKjB;IAED,yGAAyG;IACnG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAkB9B,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,UAAU;IAcT,MAAM;CAqBhB;AAqGD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,gBAAgB,EAAE,UAAU,CAAA;KAC7B;CACF"}