@llumi/design-system 1.0.1 → 2.1.0

package/copy-button.md

@@ -0,0 +1,128 @@
+# `<llumi-copy-button>`
+
+Copy-to-clipboard icon button with animated success/error feedback.
+
+## What it is
+
+A minimal icon button that copies text to the clipboard and shows live state transitions:
+
+| State | Visual |
+|-------|--------|
+| idle | copy icon |
+| copying | spinning indicator (button disabled) |
+| copied | green ✓ icon, resets after 1 s |
+| error | red × icon, resets after 1 s |
+
+---
+
+## Usage
+
+> **Requires the base theme.** This is a light-DOM element styled by the design-system stylesheet — load `@llumi/design-system/base.css` (or `base.css`) on the page, or the button renders unstyled.
+
+```html
+<!-- 1. Register the element (auto side-effect) -->
+<script type="module">
+  import "@llumi/design-system/copy-button";
+</script>
+
+<!-- 2. Drop the tag wherever you need it -->
+<llumi-copy-button value="Text to copy"></llumi-copy-button>
+```
+
+Or with named import:
+
+```js
+import { LlumiCopyButton } from "@llumi/design-system/copy-button";
+```
+
+---
+
+## Copy source precedence
+
+The text that gets written to the clipboard is resolved from the first source that is available, in this order:
+
+1. **`getValue` (JS function property)** — highest precedence. Assign a function:
+   ```js
+   document.querySelector("llumi-copy-button").getValue = () => editor.getValue();
+   ```
+2. **`get-value` (attribute)** — a dotted path to a function on `globalThis`, resolved at click time via plain property traversal (no `eval`, no `new Function`). The component warns in the console if the path does not resolve to a function:
+   ```html
+   <llumi-copy-button get-value="myApp.getSnippet"></llumi-copy-button>
+   ```
+   ```js
+   window.myApp = { getSnippet: () => editor.getValue() };
+   ```
+3. **`value` (string attribute)** — a plain, static string:
+   ```html
+   <llumi-copy-button value="npm install @llumi/design-system"></llumi-copy-button>
+   ```
+4. **`""` (empty string)** — fallback when none of the above is set.
+
+---
+
+## Attributes and properties
+
+| Name | Type | Default | Notes |
+|------|------|---------|-------|
+| `value` | `string` attr + prop | `""` | Static text to copy. Lowest-precedence source. |
+| `title` | `string` attr + prop | `"Copy to clipboard"` | Native tooltip; mirrored to `aria-label`. |
+| `getValue` | `() => string` prop only | `undefined` | JS function property. No HTML attribute equivalent. Highest-precedence source. |
+| `get-value` | `string` attr | — | Dotted path on `globalThis` resolving to a function. Resolved at click time. |
+| `disabled` | — | — | Managed internally while copying; do not set manually. |
+
+---
+
+## Events
+
+Both events bubble and are composed.
+
+### `llumi-copy`
+
+Fires on a successful clipboard write.
+
+```ts
+element.addEventListener("llumi-copy", (e: CustomEvent<{ text: string }>) => {
+  console.log("Copied:", e.detail.text);
+});
+```
+
+### `llumi-copy-error`
+
+Fires when `navigator.clipboard.writeText` rejects (e.g. permission denied in a non-HTTPS context or missing user gesture).
+
+```ts
+element.addEventListener("llumi-copy-error", (e: CustomEvent<{ error: unknown }>) => {
+  console.error("Copy failed:", e.detail.error);
+});
+```
+
+---
+
+## Styling
+
+### Styling the button (light DOM)
+
+The component renders in **light DOM**, so the inner `<button>` is a normal,
+fully styleable element — no shadow piercing required:
+
+```css
+llumi-copy-button button {
+  width: 3rem;
+  height: 3rem;
+  border-radius: 9999px;
+}
+```
+
+### CSS custom properties
+
+Each token has a sensible `oklch` fallback, so the component is usable without a design-system theme.
+
+| Token | Role | Fallback |
+|-------|------|---------|
+| `--llumi-color-success` | Border + icon colour in the copied state | `oklch(62.7% 0.194 149.214)` (green) |
+| `--llumi-color-danger` | Border + icon colour in the error state | `oklch(57.7% 0.245 27.325)` (red) |
+| `--llumi-color-surface` | Button background | `oklch(100% 0 0)` (white) |
+| `--llumi-color-border` | Button border | `oklch(92% 0.004 286.32)` (light grey) |
+| `--llumi-color-fg` | Icon colour (idle) | `oklch(21% 0.006 285.885)` (near-black) |
+| `--llumi-color-ring` | Focus-visible outline | `oklch(55.8% 0.288 302.321)` (purple) |
+| `--llumi-radius` | Button border-radius | `0.5rem` |

package/copy-button.mjs

@@ -0,0 +1,161 @@
+import { html as d } from "https://cdn.jsdelivr.net/npm/lit@3.3.3";
+import { property as u, customElement as h } from "https://cdn.jsdelivr.net/npm/lit@3.3.3/decorators.js";
+import { i as s } from "./icons-BaUbjt-v.js";
+import { L as b } from "./llumi-element-BWRwgzW5.js";
+import { defineMachine as m } from "https://cdn.jsdelivr.net/npm/yay-machine@1.5.0";
+/*! @llumi/design-system v2.1.0 | (c) 2026 pAIrprog SAS | license: https://cdn.jsdelivr.net/npm/@llumi/design-system@2.1.0/LICENSE | bundled third-party components under MIT, see NOTICE | @license */
+const p = 1e3, f = m({
+  initialState: { name: "idle" },
+  states: {
+    idle: {
+      on: {
+        COPY: { to: "copying", data: ({ event: t }) => ({ text: t.text }) }
+      }
+    },
+    copying: {
+      onEnter: ({ state: t, send: e }) => {
+        navigator.clipboard.writeText(t.text).then(() => e({ type: "COPY_SUCCESS", text: t.text })).catch((o) => e({ type: "COPY_ERROR", error: o }));
+      },
+      on: {
+        COPY_SUCCESS: { to: "copied" },
+        COPY_ERROR: { to: "error" }
+      }
+    },
+    copied: {
+      onEnter: ({ send: t }) => {
+        const e = setTimeout(() => t({ type: "DONE" }), p);
+        return () => clearTimeout(e);
+      },
+      on: {
+        DONE: { to: "idle" },
+        COPY: { to: "copying", data: ({ event: t }) => ({ text: t.text }) }
+      }
+    },
+    error: {
+      onEnter: ({ send: t }) => {
+        const e = setTimeout(() => t({ type: "DONE" }), p);
+        return () => clearTimeout(e);
+      },
+      on: {
+        DONE: { to: "idle" },
+        COPY: { to: "copying", data: ({ event: t }) => ({ text: t.text }) }
+      }
+    }
+  }
+});
+function y(t, e = globalThis) {
+  let o = e;
+  for (const r of t.split(".")) {
+    if (o == null) return;
+    o = o[r];
+  }
+  return o;
+}
+var C = Object.defineProperty, E = Object.getOwnPropertyDescriptor, c = (t, e, o, r) => {
+  for (var i = r > 1 ? void 0 : r ? E(e, o) : e, l = t.length - 1, a; l >= 0; l--)
+    (a = t[l]) && (i = (r ? a(e, o, i) : a(i)) || i);
+  return r && i && C(e, o, i), i;
+};
+function O(t) {
+  throw new Error(`Unexpected state: ${JSON.stringify(t)}`);
+}
+let n = class extends b {
+  constructor() {
+    super(...arguments), this.value = "", this.title = "Copy to clipboard";
+  }
+  /** Light DOM so the document-level base.css button style applies. */
+  createRenderRoot() {
+    return this;
+  }
+  connectedCallback() {
+    super.connectedCallback(), this.instance = f.newInstance().start(), this.unsubscribe = this.instance.subscribe(
+      ({ state: t, event: e }) => this.onTransition(t, e)
+    );
+  }
+  disconnectedCallback() {
+    var t, e;
+    super.disconnectedCallback(), (t = this.unsubscribe) == null || t.call(this), this.unsubscribe = void 0, (e = this.instance) == null || e.stop(), this.instance = void 0;
+  }
+  onTransition(t, e) {
+    (e == null ? void 0 : e.type) === "COPY_SUCCESS" ? this.dispatchEvent(
+      new CustomEvent("llumi-copy", {
+        detail: { text: e.text },
+        bubbles: !0,
+        composed: !0
+      })
+    ) : (e == null ? void 0 : e.type) === "COPY_ERROR" && this.dispatchEvent(
+      new CustomEvent("llumi-copy-error", {
+        detail: { error: e.error },
+        bubbles: !0,
+        composed: !0
+      })
+    ), this.requestUpdate();
+  }
+  /**
+   * Resolve the text to copy, by precedence:
+   *   getValue() (function prop)
+   *   → get-value (attribute: dotted path to a function on globalThis, resolved at click time)
+   *   → value (string attr)
+   *   → ""
+   */
+  resolveText() {
+    if (typeof this.getValue == "function") return this.getValue();
+    const t = this.getAttribute("get-value");
+    if (t) {
+      const e = y(t);
+      if (typeof e == "function")
+        return String(e());
+      console.warn(
+        `<llumi-copy-button>: get-value="${t}" did not resolve to a function on globalThis`
+      );
+    }
+    return this.value ?? "";
+  }
+  onClick() {
+    var t;
+    (t = this.instance) == null || t.send({ type: "COPY", text: this.resolveText() });
+  }
+  viewFor(t) {
+    switch (t) {
+      case "idle":
+        return { icon: s.copy, cls: "" };
+      case "copying":
+        return { icon: s.spinner, cls: "is-working" };
+      case "copied":
+        return { icon: s.check, cls: "is-done" };
+      case "error":
+        return { icon: s.x, cls: "is-error" };
+      default:
+        return O(t);
+    }
+  }
+  render() {
+    var o;
+    const t = ((o = this.instance) == null ? void 0 : o.state.name) ?? "idle", e = this.viewFor(t);
+    return d`<button
+			type="button"
+			class=${e.cls}
+			title=${this.title}
+			aria-label=${this.title}
+			?disabled=${t === "copying"}
+			@click=${this.onClick}
+		>
+			<i>${e.icon}</i>
+		</button>`;
+  }
+};
+c([
+  u()
+], n.prototype, "value", 2);
+c([
+  u()
+], n.prototype, "title", 2);
+c([
+  u({ attribute: !1 })
+], n.prototype, "getValue", 2);
+n = c([
+  h("llumi-copy-button")
+], n);
+export {
+  n as LlumiCopyButton
+};