@kahitsan/ksui 0.3.0 → 0.4.0

package/src/components/base/Tooltip.tsx

@@ -0,0 +1,64 @@
+import { createUniqueId, type JSX } from "solid-js";
+
+interface TooltipProps {
+  /** Text or JSX to show inside the tooltip bubble. */
+  content: JSX.Element;
+  /** Where the bubble sits relative to the trigger. Default "top". */
+  placement?: "top" | "bottom";
+  /** Allow the trigger to be any element; the wrapper is a span. */
+  children: JSX.Element;
+  /** Extra classes on the wrapper. The wrapper is inline-flex so it sits
+   *  cleanly inside flex rows next to the trigger element. */
+  class?: string;
+  /** Optional explicit id for the tooltip element. Auto-generated via
+   *  `createUniqueId()` when omitted. Callers can pass this id forward
+   *  as `aria-describedby` on a deeper focusable trigger when the wrapper
+   *  span isn't the focusable surface — the W3C tooltip pattern wants
+   *  describedby on the trigger itself, not on an ancestor. The wrapper
+   *  also carries the same describedby so SRs that read by element type
+   *  surface the description on the way through. */
+  id?: string;
+}
+
+// Lightweight hover/focus tooltip. CSS-only — no JS positioning, no portal.
+// Anchors to the trigger via group-hover and stays out of layout (absolute).
+// For dense / clipped containers, prefer a portal-based picker instead; this
+// is for short copy on buttons and chips ("Mark as payer", "Removes
+// selections; nothing else is lost", etc.) that needs to read more clearly
+// than the native `title=` attribute.
+//
+// A11y notes:
+//   - The bubble carries `role="tooltip"` and a stable id, so assistive
+//     tech can find it via the AT tree. We removed an earlier `aria-hidden`
+//     because it actively contradicted the role: ATs saw "tooltip" and
+//     then "skip me", which left screen-reader users with a tooltip
+//     advertised but unreadable.
+//   - The wrapper carries `aria-describedby={tooltipId}` so navigating
+//     into the wrapper surfaces the description. The W3C tooltip pattern
+//     prefers describedby on the focusable trigger itself; since the
+//     trigger is `props.children` (any element) and Solid has no
+//     cloneElement, the trigger-level wiring lives with the caller in
+//     specific cases that need it. See #627 for the broader sweep that
+//     introduces a directive-based wiring API.
+export default function Tooltip(props: TooltipProps): JSX.Element {
+  const tooltipId = props.id ?? createUniqueId();
+  const placement = () => props.placement ?? "top";
+  return (
+    <span
+      class={`relative inline-flex group/tt ${props.class ?? ""}`}
+      data-tooltip-wrap
+      aria-describedby={tooltipId}
+    >
+      {props.children}
+      <span
+        role="tooltip"
+        id={tooltipId}
+        class={`pointer-events-none absolute left-1/2 -translate-x-1/2 px-2 py-1 rounded-md bg-zinc-900 border border-zinc-700/80 text-[11px] text-zinc-100 whitespace-nowrap opacity-0 group-hover/tt:opacity-100 group-focus-within/tt:opacity-100 transition-opacity duration-150 delay-150 z-50 shadow-lg ${
+          placement() === "bottom" ? "top-full mt-1" : "bottom-full mb-1"
+        }`}
+      >
+        {props.content}
+      </span>
+    </span>
+  );
+}

package/src/components/{ClientPicker.tsx → composite/ClientPicker.tsx}

@@ -1,7 +1,7 @@
 // Source: KahitSan/kserp src/components/ClientPicker.tsx (vendored into the plugin remote).
 //
 // Cross-plugin picker: fetches the SIBLING clients plugin's public API at
-// /api/clients. Degrades gracefully — when the clients plugin isn't deployed
+// /api/clients. Degrades gracefully: when the clients plugin isn't deployed
 // the fetch 404s/fails, the popup shows an inline "couldn't load" notice, and
 // the rest of the transaction modal still works (the sale just has no
 // billed-to client). highlightMatch comes from the host UI kit.

package/src/components/composite/FormActions.tsx

@@ -0,0 +1,79 @@
+// Cancel / Submit modal footer row, composing the host Button.
+//
+// The same footer is repeated across plugin modals: a
+// `flex flex-col-reverse sm:flex-row gap-2 sm:justify-end` row with a
+// secondary Cancel button and a primary submit button (often disabled while
+// saving, sometimes with a leading icon). This promotes that footer layout and
+// the standard Cancel/Submit wiring, leaving all domain concerns (labels,
+// handlers, saving state, optional icon) as props. No fetch/API call lives
+// here — the caller owns the submit handler.
+//
+// ModalShell is deliberately NOT promoted: the host Modal already supplies the
+// backdrop, card, title/close-X path, aria-modal, focus trap, size and tone
+// tokens. Only the body chrome the host Modal does not cover (FormErrorBanner +
+// FormActions) is promoted.
+
+import type { JSX } from "solid-js";
+import { Show } from "solid-js";
+import { Button } from "@kserp/host-ui";
+
+export interface FormActionsProps {
+  /** Invoked when the Cancel button is clicked. */
+  onCancel: () => void;
+  /**
+   * Invoked when the Submit button is clicked. Omit when `submitType="submit"`
+   * and let the wrapping <form> handle submission.
+   */
+  onSubmit?: () => void;
+  /** Primary button label. Defaults to "Save". */
+  submitLabel?: string;
+  /** Secondary button label. Defaults to "Cancel". */
+  cancelLabel?: string;
+  /** When true, disables the submit button (in-flight save). */
+  submitting?: boolean;
+  /** Extra condition to disable the submit button. */
+  submitDisabled?: boolean;
+  /** Optional leading icon rendered before the submit label. */
+  submitIcon?: JSX.Element;
+  /**
+   * Button type for the submit action. Defaults to "button" (handler-driven).
+   * Set to "submit" to let a wrapping <form> handle the action; in that case
+   * `onSubmit` is ignored.
+   */
+  submitType?: "button" | "submit";
+  /** Swap the primary button to a destructive tone. */
+  danger?: boolean;
+  /** Extra classes appended to the footer row. */
+  class?: string;
+}
+
+export default function FormActions(props: FormActionsProps): JSX.Element {
+  const isSubmitType = () => props.submitType === "submit";
+  return (
+    <div
+      class={
+        "flex flex-col-reverse sm:flex-row gap-2 sm:justify-end" +
+        (props.class ? " " + props.class : "")
+      }
+    >
+      <Button
+        type="button"
+        onClick={props.onCancel}
+        intent="secondary"
+        class="w-full sm:w-auto"
+      >
+        {props.cancelLabel ?? "Cancel"}
+      </Button>
+      <Button
+        type={isSubmitType() ? "submit" : "button"}
+        onClick={isSubmitType() ? undefined : props.onSubmit}
+        disabled={(props.submitting ?? false) || (props.submitDisabled ?? false)}
+        intent={props.danger ? "danger" : "primary"}
+        class="gap-2 w-full sm:w-auto"
+      >
+        <Show when={props.submitIcon}>{props.submitIcon}</Show>
+        {props.submitLabel ?? "Save"}
+      </Button>
+    </div>
+  );
+}

package/src/components/composite/LiveTimer.tsx

@@ -0,0 +1,434 @@
+// Source: archive/pillar app/pillar-ui/composite/LiveTimer/LiveTimer.tsx
+// Reusable realtime / overdue progress display. The ticker module-state
+// is shared across all LiveTimer instances on the page so we don't run
+// N intervals when N cards are on screen — the home page session
+// manager already proved this pattern at scale, so we lift it as-is.
+
+import type { Component, JSX } from "solid-js";
+import { Show, createMemo, createSignal, onCleanup, splitProps } from "solid-js";
+import Clock from "lucide-solid/icons/clock";
+import Play from "lucide-solid/icons/play";
+import AlertTriangle from "lucide-solid/icons/triangle-alert";
+import Check from "lucide-solid/icons/check";
+import Calendar from "lucide-solid/icons/calendar";
+import ProgressBar from "../base/ProgressBar";
+
+export interface LiveTimerProps extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "class"> {
+  // Core timing
+  startAt: Date | string | number;
+  endAt?: Date | string | number | null;
+  // When true, the timer keeps counting past `endAt` (red overdue
+  // visualization) instead of switching to the completed look.
+  overdue?: boolean;
+  // Optional icon override; default picks one based on scenario.
+  icon?: Component<{ size: number; class?: string }>;
+  // Optional class merged onto the underlying ProgressBar.
+  class?: string;
+  // Overrides the scenario's default right-side label (e.g. swap the
+  // built-in "Remaining" for a total-duration label like "9h").
+  // `null` hides the label entirely.
+  label?: string | null;
+  // Force-hide the percentage readout regardless of scenario default.
+  // Counter pills don't surface percentages; the home page might.
+  hidePercentage?: boolean;
+  // When set, swaps the pill layout to total-left / countdown-right:
+  //   [icon] {totalLabel}                                 {countdown}
+  // Caller-provided string sits on the LEFT next to the icon; the live
+  // countdown moves to the RIGHT where the percentage used to sit.
+  // Counter cards use this so cashiers see "4h total" + "5h 23:45" on
+  // one row without ellipsis.
+  totalLabel?: string;
+}
+
+// Dynamic tick — 1s under 24h remaining, 5min over. Shared module-state
+// so the page runs at most ONE interval no matter how many LiveTimers
+// are mounted.
+let dynamicTickSignal: (() => number) | null = null;
+let dynamicIntervalId: ReturnType<typeof setInterval> | null = null;
+let dynamicSubscriberCount = 0;
+let currentInterval = 1000;
+
+function getDynamicTick(startSec: number, endSec: number | null, overdue: boolean): () => number {
+  if (!dynamicTickSignal) {
+    const [tick, setTick] = createSignal(Date.now());
+    dynamicTickSignal = tick;
+
+    const updateInterval = () => {
+      const nowSec = Math.floor(Date.now() / 1000);
+      const HOURS_24 = 24 * 3600;
+      let newInterval = 1000;
+      if (nowSec <= startSec) {
+        const rem = startSec - nowSec;
+        newInterval = rem > HOURS_24 ? 300000 : 1000;
+      } else if (endSec !== null && nowSec < endSec) {
+        const rem = endSec - nowSec;
+        newInterval = rem > HOURS_24 ? 300000 : 1000;
+      } else if (endSec !== null && nowSec >= endSec && overdue) {
+        const od = nowSec - endSec;
+        newInterval = od > HOURS_24 ? 300000 : 1000;
+      }
+      if (newInterval !== currentInterval) {
+        currentInterval = newInterval;
+        if (dynamicIntervalId) clearInterval(dynamicIntervalId);
+        dynamicIntervalId = setInterval(() => {
+          setTick(Date.now());
+          updateInterval();
+        }, currentInterval);
+      }
+    };
+
+    dynamicIntervalId = setInterval(() => {
+      setTick(Date.now());
+      updateInterval();
+    }, currentInterval);
+  }
+
+  dynamicSubscriberCount++;
+
+  onCleanup(() => {
+    dynamicSubscriberCount--;
+    if (dynamicSubscriberCount === 0 && dynamicIntervalId) {
+      clearInterval(dynamicIntervalId);
+      dynamicIntervalId = null;
+      dynamicTickSignal = null;
+      currentInterval = 1000;
+    }
+  });
+
+  return dynamicTickSignal;
+}
+
+// Slow tick — 10s, for heavy calculations (progress + scenario) that
+// don't need second-level accuracy.
+let slowTickSignal: (() => number) | null = null;
+let slowIntervalId: ReturnType<typeof setInterval> | null = null;
+let slowSubscriberCount = 0;
+
+function getSlowTick(): () => number {
+  if (!slowTickSignal) {
+    const [tick, setTick] = createSignal(Date.now());
+    slowTickSignal = tick;
+    slowIntervalId = setInterval(() => setTick(Date.now()), 10000);
+  }
+  slowSubscriberCount++;
+  onCleanup(() => {
+    slowSubscriberCount--;
+    if (slowSubscriberCount === 0 && slowIntervalId) {
+      clearInterval(slowIntervalId);
+      slowIntervalId = null;
+      slowTickSignal = null;
+    }
+  });
+  return slowTickSignal;
+}
+
+function ensureDate(value: Date | string | number | null | undefined): Date | undefined {
+  if (value == null) return undefined;
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? undefined : value;
+  try {
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) return undefined;
+    return d;
+  } catch {
+    return undefined;
+  }
+}
+
+const PAD = ["00", "01", "02", "03", "04", "05", "06", "07", "08", "09"];
+function pad2(n: number): string {
+  return n < 10 ? PAD[n] : String(n);
+}
+
+// Compact countdown / elapsed format. Spec from the counter cards:
+//   * >= 1 day  → "Xd Yh"           (seconds aren't worth watching at this scale)
+//   * >= 1 hour → "Xh MM:SS"        (mixed unit, mm:ss keeps it readable)
+//   * < 1 hour  → "MM:SS"           (compact urgency)
+// Returns "0:00" for negatives so an overdue render that briefly hits 0
+// doesn't blink to "-1:..".
+function formatLiveTimer(totalSeconds: number): string {
+  if (!Number.isFinite(totalSeconds) || totalSeconds <= 0) return "00:00";
+  const HOURS_24 = 24 * 3600;
+  if (totalSeconds >= HOURS_24) {
+    const d = Math.floor(totalSeconds / 86400);
+    const h = Math.floor((totalSeconds % 86400) / 3600);
+    return `${d}d ${h}h`;
+  }
+  if (totalSeconds >= 3600) {
+    const h = Math.floor(totalSeconds / 3600);
+    const m = Math.floor((totalSeconds % 3600) / 60);
+    const s = Math.floor(totalSeconds % 60);
+    return `${h}h ${pad2(m)}:${pad2(s)}`;
+  }
+  const m = Math.floor(totalSeconds / 60);
+  const s = Math.floor(totalSeconds % 60);
+  return `${pad2(m)}:${pad2(s)}`;
+}
+
+// Back-compat alias for any caller still expecting the older name.
+function formatTimeWithDays(totalSeconds: number): string {
+  return formatLiveTimer(totalSeconds);
+}
+
+function formatDuration(totalSeconds: number): string {
+  const h = Math.floor(totalSeconds / 3600);
+  const m = Math.floor((totalSeconds % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+const SCENARIO_COUNTDOWN_TO_START = 0;
+const SCENARIO_OPEN_TIMER = 1;
+const SCENARIO_OVERDUE = 2;
+const SCENARIO_COMPLETED = 3;
+const SCENARIO_COUNTDOWN_TIMER = 4;
+type Scenario =
+  | typeof SCENARIO_COUNTDOWN_TO_START
+  | typeof SCENARIO_OPEN_TIMER
+  | typeof SCENARIO_OVERDUE
+  | typeof SCENARIO_COMPLETED
+  | typeof SCENARIO_COUNTDOWN_TIMER;
+
+interface ScenarioConfig {
+  position: "left" | "right";
+  colorClass: string;
+  label: string | undefined;
+  hidePercentage: boolean;
+  shimmer: boolean;
+}
+
+const SCENARIO_CONFIGS: Record<Scenario, ScenarioConfig> = {
+  [SCENARIO_COUNTDOWN_TO_START]: {
+    position: "right",
+    colorClass: "border border-blue-600/60 text-blue-400 hover:border-blue-500",
+    // Active board card uses this to read "[icon] 4h total · Starts in
+    // <countdown>" so the cashier sees both the package total and that
+    // the rental is a future booking, not an in-progress one.
+    label: "Starts in",
+    hidePercentage: true,
+    shimmer: false,
+  },
+  [SCENARIO_OPEN_TIMER]: {
+    position: "left",
+    colorClass: "border border-green-600/60 text-green-400 hover:border-green-500",
+    label: "Open time",
+    hidePercentage: true,
+    shimmer: true,
+  },
+  [SCENARIO_OVERDUE]: {
+    position: "left",
+    colorClass: "border border-purple-600/60 text-purple-400 hover:border-purple-500",
+    label: "Overdue",
+    hidePercentage: false,
+    shimmer: false,
+  },
+  [SCENARIO_COMPLETED]: {
+    position: "left",
+    colorClass: "border border-zinc-600/60 text-zinc-400 hover:border-zinc-500",
+    label: "Completed",
+    hidePercentage: false,
+    shimmer: false,
+  },
+  [SCENARIO_COUNTDOWN_TIMER]: {
+    position: "left",
+    colorClass: "",
+    label: "Remaining",
+    hidePercentage: false,
+    shimmer: false,
+  },
+};
+
+const COLOR_GREEN = "border border-green-600/60 text-green-400 hover:border-green-500";
+const COLOR_AMBER = "border border-amber-600/60 text-amber-400 hover:border-amber-500";
+const COLOR_RED = "border border-red-600/60 text-red-400 hover:border-red-500";
+
+const LiveTimer: Component<LiveTimerProps> = (props) => {
+  const [local, others] = splitProps(props, [
+    "startAt",
+    "endAt",
+    "overdue",
+    "icon",
+    "class",
+    "label",
+    "hidePercentage",
+    "totalLabel",
+  ]);
+
+  const timestamps = createMemo(() => {
+    const start = ensureDate(local.startAt);
+    if (!start) throw new Error("LiveTimer: startAt must be a valid Date or date string");
+    const end = ensureDate(local.endAt ?? null);
+    return {
+      startSec: Math.floor(start.getTime() / 1000),
+      endSec: end ? Math.floor(end.getTime() / 1000) : null,
+    };
+  });
+
+  // Subscribe to the shared tickers.
+  const { startSec, endSec } = timestamps();
+  const dynamicTick = getDynamicTick(startSec, endSec, local.overdue ?? false);
+  const slowTick = getSlowTick();
+
+  const scenario = createMemo<Scenario>(() => {
+    const nowSec = Math.floor(slowTick() / 1000);
+    const { startSec: s, endSec: e } = timestamps();
+    if (nowSec <= s) return SCENARIO_COUNTDOWN_TO_START;
+    if (e === null) return SCENARIO_OPEN_TIMER;
+    const done = nowSec >= e;
+    if (done && local.overdue) return SCENARIO_OVERDUE;
+    if (done) return SCENARIO_COMPLETED;
+    return SCENARIO_COUNTDOWN_TIMER;
+  });
+
+  const progress = createMemo(() => {
+    const nowSec = Math.floor(slowTick() / 1000);
+    const { startSec: s, endSec: e } = timestamps();
+    switch (scenario()) {
+      case SCENARIO_COUNTDOWN_TO_START: {
+        const rem = s - nowSec;
+        return Math.min(100, (rem / 3600) * 100);
+      }
+      case SCENARIO_OPEN_TIMER:
+        return 95;
+      case SCENARIO_OVERDUE: {
+        const od = nowSec - (e ?? nowSec);
+        const total = (e ?? 0) - s;
+        const pct = total > 0 ? (od / total) * 100 : 0;
+        return 100 + pct;
+      }
+      case SCENARIO_COMPLETED:
+        return 100;
+      case SCENARIO_COUNTDOWN_TIMER: {
+        const rem = (e ?? nowSec) - nowSec;
+        const total = (e ?? 0) - s;
+        const elapsed = total - rem;
+        return total > 0 ? Math.min(100, (elapsed / total) * 100) : 100;
+      }
+      default:
+        return 0;
+    }
+  });
+
+  const statusLabel = createMemo(() => {
+    const nowSec = Math.floor(dynamicTick() / 1000);
+    const { startSec: s, endSec: e } = timestamps();
+    switch (scenario()) {
+      case SCENARIO_COUNTDOWN_TO_START:
+        return formatTimeWithDays(s - nowSec);
+      case SCENARIO_OPEN_TIMER:
+        return formatTimeWithDays(nowSec - s);
+      case SCENARIO_OVERDUE:
+        return formatTimeWithDays(nowSec - (e ?? nowSec));
+      case SCENARIO_COMPLETED:
+        return formatDuration((e ?? 0) - s);
+      case SCENARIO_COUNTDOWN_TIMER:
+        return formatTimeWithDays((e ?? nowSec) - nowSec);
+      default:
+        return "00:00:00";
+    }
+  });
+
+  const staticConfig = createMemo(() => SCENARIO_CONFIGS[scenario()]);
+
+  const icon = createMemo<Component<{ size: number; class?: string }>>(() => {
+    if (local.icon) return local.icon;
+    switch (scenario()) {
+      case SCENARIO_COUNTDOWN_TO_START:
+        return Calendar;
+      case SCENARIO_OPEN_TIMER:
+        return Play;
+      case SCENARIO_OVERDUE:
+        return AlertTriangle;
+      case SCENARIO_COMPLETED:
+        return Check;
+      case SCENARIO_COUNTDOWN_TIMER:
+      default:
+        return Clock;
+    }
+  });
+
+  const colorClass = createMemo(() => {
+    if (scenario() === SCENARIO_COUNTDOWN_TIMER) {
+      const p = progress();
+      return p <= 25 ? COLOR_GREEN : p <= 75 ? COLOR_AMBER : COLOR_RED;
+    }
+    return staticConfig().colorClass;
+  });
+
+  const finalClass = createMemo(() => {
+    const user = local.class ?? "";
+    if (user.includes("border-") && user.includes("text-")) return user;
+    return `${colorClass()} ${user}`.trim();
+  });
+
+  const resolvedLabel = createMemo(() => {
+    // `null` is the explicit "no label" signal from the caller; an
+    // undefined `local.label` falls through to the scenario default
+    // ("Remaining" etc.).
+    if (local.label === null) return undefined;
+    if (local.label !== undefined) return local.label;
+    return staticConfig().label;
+  });
+
+  const resolvedHidePercentage = createMemo(() => {
+    return local.hidePercentage ?? staticConfig().hidePercentage;
+  });
+
+  // Scenario context label sits after the totalLabel on the left so the
+  // cashier sees "[icon] 4h total · Starts in" / "… · Overdue" without
+  // hiding the countdown. Running countdowns (the common case) skip it
+  // — the right-side ticker already carries the time-remaining cue.
+  const scenarioContextLabel = createMemo(() => {
+    switch (scenario()) {
+      case SCENARIO_COUNTDOWN_TO_START:
+        return "Starts in";
+      case SCENARIO_OVERDUE:
+        return "Overdue";
+      case SCENARIO_OPEN_TIMER:
+        return "Open";
+      default:
+        return undefined;
+    }
+  });
+
+  // Layout mode A — caller passed `totalLabel`. Show the total label on
+  // the left and the live countdown on the right. No secondary label,
+  // no percentage. This is what the counter cards use so cashiers read
+  // "4h total" + "5h 23:45" without competing text.
+  // Layout mode B — default. statusLabel carries the countdown on the
+  // left, scenario label sits after it, percentage renders on the
+  // right (unless `hidePercentage`). Matches the home page session
+  // manager's original look.
+  return (
+    <Show
+      when={local.totalLabel !== undefined}
+      fallback={
+        <ProgressBar
+          progress={progress()}
+          icon={icon()}
+          statusLabel={statusLabel()}
+          label={resolvedLabel()}
+          position={staticConfig().position}
+          hidePercentage={resolvedHidePercentage()}
+          shimmer={staticConfig().shimmer}
+          class={finalClass()}
+          {...others}
+        />
+      }
+    >
+      <ProgressBar
+        progress={progress()}
+        icon={icon()}
+        statusLabel={local.totalLabel}
+        label={scenarioContextLabel()}
+        position={staticConfig().position}
+        hidePercentage
+        rightLabel={statusLabel()}
+        shimmer={staticConfig().shimmer}
+        class={finalClass()}
+        {...others}
+      />
+    </Show>
+  );
+};
+
+export default LiveTimer;

package/src/components/{MarkdownNotes.tsx → composite/MarkdownNotes.tsx}

@@ -334,7 +334,7 @@ function MentionChip(props: { name: string; clientId: number | null }): JSX.Elem
     const perms = usePermissions();
     canViewClients = () => perms.has("clients.view");
   } catch {
-    /* no provider in context — leave canViewClients() returning false */
+    /* no provider in context, leave canViewClients() returning false */
   }
 
   return (

package/src/components/{PaymentAccountPicker.tsx → composite/PaymentAccountPicker.tsx}

@@ -11,7 +11,7 @@ import {
 } from "solid-js";
 import Banknote from "lucide-solid/icons/banknote";
 import Loader2 from "lucide-solid/icons/loader-2";
-import AccountAvatar from "./AccountAvatar";
+import AccountAvatar from "../base/AccountAvatar";
 
 export interface PaymentAccountOption {
   id: number;
@@ -102,7 +102,7 @@ export default function PaymentAccountPicker(props: PaymentAccountPickerProps):
     }
   };
 
-  // Single fetch at mount — list rarely changes within a cart session,
+  // Single fetch at mount. The list rarely changes within a cart session,
   // and Charge gating already depends on the count it reports up via
   // onCountChange. If the picker ever needs to refetch on org switch,
   // swap this for a createEffect tracking the active-org signal.

package/src/components/composite/SecretReveal.tsx

@@ -0,0 +1,63 @@
+// Source: kplugin_user-api-keys/ui/remote/index.tsx (reveal-once callout)
+// and the identical block in kplugin_api-keys. A presentational, domain-free
+// "save this secret now" callout: an amber bordered box with a warning line, a
+// monospace code showing the secret value, a copy button, and an optional
+// footer caption. The caller decides when to mount it (wrap in
+// <Show when={revealed()}>); this component holds no fetch, no plugin state.
+
+import type { Component } from "solid-js";
+import { Show, createSignal, splitProps } from "solid-js";
+import Copy from "lucide-solid/icons/copy";
+
+export interface SecretRevealProps {
+  /** The secret string to display and copy. */
+  secret: string;
+  /** Warning line shown above the secret. */
+  warning?: string;
+  /** Optional footer caption, e.g. "Key for: agentic-laptop". */
+  caption?: string;
+  /** Optional test id applied to the monospace secret code element. */
+  testId?: string;
+}
+
+const DEFAULT_WARNING = "Save this now - it will not be shown again.";
+
+const SecretReveal: Component<SecretRevealProps> = (props) => {
+  const [local] = splitProps(props, ["secret", "warning", "caption", "testId"]);
+  const [copied, setCopied] = createSignal(false);
+
+  const copy = () => {
+    navigator.clipboard.writeText(local.secret).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    });
+  };
+
+  return (
+    <div class="mb-4 p-3 rounded-lg bg-amber-500/10 border border-amber-500/20">
+      <p class="text-xs text-amber-300 font-medium mb-2">{local.warning ?? DEFAULT_WARNING}</p>
+      <div class="flex items-center gap-2">
+        <code
+          data-testid={local.testId}
+          class="flex-1 px-2 py-1.5 rounded bg-zinc-900 border border-zinc-700 text-amber-200 text-xs font-mono break-all"
+        >
+          {local.secret}
+        </code>
+        <button
+          type="button"
+          onClick={copy}
+          class="ks-interactive px-2 py-1.5 rounded bg-zinc-800 border border-zinc-700 text-zinc-300 hover:text-white text-xs flex items-center gap-1"
+          aria-label="Copy secret"
+        >
+          <Copy size={12} />
+          {copied() ? "Copied" : "Copy"}
+        </button>
+      </div>
+      <Show when={local.caption}>
+        <p class="text-[10px] text-zinc-500 mt-2">{local.caption}</p>
+      </Show>
+    </div>
+  );
+};
+
+export default SecretReveal;

package/src/components/{VoucherPicker.tsx → composite/VoucherPicker.tsx}

@@ -1,7 +1,7 @@
 // Source: KahitSan/kserp src/components/VoucherPicker.tsx (vendored into the plugin remote).
 //
 // Cross-plugin picker: fetches the SIBLING vouchers plugin's public API at
-// /api/vouchers and degrades gracefully — when the vouchers plugin isn't
+// /api/vouchers and degrades gracefully: when the vouchers plugin isn't
 // deployed the popup shows a "couldn't load" notice and the sale records with
 // no voucher (the manual-discount field stays available).