@karyl-chan/ui 0.1.0

package/src/composables/use-shift-key.ts

@@ -0,0 +1,18 @@
+import { onMounted, onUnmounted, ref } from 'vue'
+
+export function useShiftKey() {
+    const held = ref(false)
+    function track(event: KeyboardEvent) { held.value = event.shiftKey }
+    function release() { held.value = false }
+    onMounted(() => {
+        document.addEventListener('keydown', track)
+        document.addEventListener('keyup', track)
+        window.addEventListener('blur', release)
+    })
+    onUnmounted(() => {
+        document.removeEventListener('keydown', track)
+        document.removeEventListener('keyup', track)
+        window.removeEventListener('blur', release)
+    })
+    return held
+}

package/src/index.ts

@@ -0,0 +1,75 @@
+// @karyl-chan/ui — shared Vue UI for karyl-chan bot frontend and plugin webuis.
+//
+// Side-effect CSS imports must be done separately by the consumer (so they
+// can choose order and avoid double-importing):
+//   import "@karyl-chan/ui/tokens.css";
+//   import "@karyl-chan/ui/reset.css";
+//   import "@karyl-chan/ui/use-drawer.css";
+//   import "@karyl-chan/ui/use-popover.css";
+
+// ── Components ───────────────────────────────────────────────────────────
+export { default as AppBadge } from "./components/AppBadge.vue";
+export type { BadgeSize, BadgeTone, BadgeVariant } from "./components/AppBadge.vue";
+export { default as AppButton } from "./components/AppButton.vue";
+export { default as AppConfirmDialog } from "./components/AppConfirmDialog.vue";
+export { default as AppItemCard } from "./components/AppItemCard.vue";
+export type { AccentBarTone } from "./components/AppItemCard.vue";
+export { default as AppMenu } from "./components/AppMenu.vue";
+export { default as AppMenuItem } from "./components/AppMenuItem.vue";
+export { default as AppModal } from "./components/AppModal.vue";
+export { default as AppPopover } from "./components/AppPopover.vue";
+export { default as AppSelect } from "./components/AppSelect.vue";
+export { default as AppSelectField } from "./components/AppSelectField.vue";
+export type { SelectOption } from "./components/AppSelectField.vue";
+export { default as AppTabs } from "./components/AppTabs.vue";
+export type { TabDef } from "./components/tab-types";
+export { default as AppTextArea } from "./components/AppTextArea.vue";
+export { default as AppTextField } from "./components/AppTextField.vue";
+export { default as AppToggle } from "./components/AppToggle.vue";
+// AppTabsRouted carries a vue-router dependency. Importing it from a
+// plugin SPA that doesn't have vue-router installed will fail at build
+// time — that's the intended boundary. The non-routed AppTabs above
+// has no such dependency.
+export { default as AppTabsRouted } from "./components/AppTabsRouted.vue";
+export { default as AppToast } from "./components/AppToast.vue";
+export { default as Draggable } from "./components/Draggable.vue";
+export { default as GlobalConfirmDialog } from "./components/GlobalConfirmDialog.vue";
+export { default as UnreadPill } from "./components/UnreadPill.vue";
+export { default as UserAvatar } from "./components/UserAvatar.vue";
+export { default as UserCard } from "./components/UserCard.vue";
+export { default as UserItem } from "./components/UserItem.vue";
+
+// ── Lib helpers ──────────────────────────────────────────────────────────
+export {
+  isAnimatedAvatar,
+  isAnimatedBanner,
+  animatedAvatarUrl,
+} from "./lib/avatar";
+
+// ── Composables ──────────────────────────────────────────────────────────
+export {
+  useAppShell,
+  provideAppShell,
+  useFlushMain,
+  useOverlayExtras,
+} from "./composables/use-app-shell";
+export type { AppShellContext, OverlayView } from "./composables/use-app-shell";
+export { useBreakpoint } from "./composables/use-breakpoint";
+export { useClickOutsideStack } from "./composables/use-click-outside-stack";
+export { useColorScheme } from "./composables/use-color-scheme";
+export type { ColorScheme } from "./composables/use-color-scheme";
+export { useConfirm } from "./composables/use-confirm";
+export type { ConfirmOptions } from "./composables/use-confirm";
+export { useDrawer } from "./composables/use-drawer";
+export type { DrawerPlacement, UseDrawerOptions } from "./composables/use-drawer";
+export { useEscapeStack } from "./composables/use-escape-stack";
+export { useFileDrop } from "./composables/use-file-drop";
+export type { FileDropHandlers } from "./composables/use-file-drop";
+export { useLongPress } from "./composables/use-long-press";
+export { usePopover } from "./composables/use-popover";
+export type { Placement, UsePopoverOptions } from "./composables/use-popover";
+export { useShiftKey } from "./composables/use-shift-key";
+
+// ── Stores ───────────────────────────────────────────────────────────────
+export { useToastStore } from "./stores/toastStore";
+export type { ToastItem } from "./stores/toastStore";

package/src/lib/avatar.ts

@@ -0,0 +1,35 @@
+// Discord CDN avatar / banner helpers.
+//
+// Discord encodes animated assets with an `a_` hash prefix. The `.webp`
+// endpoint serves the still frame by default and the animated variant
+// when `&animated=true` is appended (Discord CDN honours this query
+// parameter; the .gif endpoint returns 415 for many assets so we stay
+// on .webp). Consumers opt into animation selectively — hover on a
+// list row vs. always-playing inside a profile card.
+
+/**
+ * True if the URL points at an animated avatar — either global
+ * (`/avatars/<userId>/a_…`) or guild-specific
+ * (`/guilds/<gid>/users/<uid>/avatars/a_…`).
+ */
+export function isAnimatedAvatar(url: string | null | undefined): boolean {
+  if (!url) return false;
+  return /\/avatars\/(?:\d+\/)?a_/.test(url);
+}
+
+/** True if the URL points at an animated banner. */
+export function isAnimatedBanner(url: string | null | undefined): boolean {
+  if (!url) return false;
+  return /\/banners\/\d+\/a_/.test(url);
+}
+
+/**
+ * Append `animated=true` so the Discord CDN returns the animated frame.
+ * Idempotent if the caller already added it; callers should still gate
+ * via `isAnimatedAvatar` / `isAnimatedBanner` first — appending the
+ * param to a still-only asset is a wasted request.
+ */
+export function animatedAvatarUrl(url: string): string {
+  if (/[?&]animated=true(?:&|$)/.test(url)) return url;
+  return url.includes("?") ? `${url}&animated=true` : `${url}?animated=true`;
+}

package/src/reset.css

@@ -0,0 +1,53 @@
+/* @karyl-chan/ui — minimal reset + base typography.
+ * Import once from your app entry: `import "@karyl-chan/ui/reset.css"`.
+ * Pairs with tokens.css (provides --text / --bg-page / --link).
+ */
+*,
+*::before,
+*::after {
+    box-sizing: border-box;
+}
+
+html,
+body,
+#app {
+    margin: 0;
+    padding: 0;
+    height: 100%;
+    overflow: hidden;
+}
+
+body {
+    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans TC", sans-serif;
+    color: var(--text);
+    background: var(--bg-page);
+    font-size: 15px;
+    line-height: 1.5;
+    overflow: hidden;
+    overscroll-behavior: none;
+}
+
+h1, h2, h3, h4 {
+    margin-top: 0;
+    color: var(--text-strong);
+}
+
+a {
+    color: var(--link);
+}
+
+/* Ghost (outlined, transparent bg) button base — covers the 80% that
+   is identical across every usage site. Padding, font-size, and
+   border-radius are NOT set here because they differ per context;
+   each call site provides its own scoped override. */
+.btn-ghost {
+    background: none;
+    border: 1px solid var(--border);
+    color: var(--text);
+    cursor: pointer;
+    font: inherit;
+}
+.btn-ghost:hover:not(:disabled) { background: var(--bg-surface-hover); }
+.btn-ghost:disabled { opacity: 0.5; cursor: default; }
+.btn-ghost.danger { color: var(--danger); border-color: rgba(239, 68, 68, 0.45); }
+.btn-ghost.danger:hover { background: rgba(239, 68, 68, 0.1); }

package/src/stores/toastStore.ts

@@ -0,0 +1,26 @@
+import { defineStore } from "pinia";
+import { ref } from "vue";
+
+export interface ToastItem {
+  id: number;
+  message: string;
+  type: "error" | "info";
+}
+
+let nextId = 0;
+
+export const useToastStore = defineStore("toast", () => {
+  const items = ref<ToastItem[]>([]);
+
+  function show(message: string, type: ToastItem["type"] = "error") {
+    const id = nextId++;
+    items.value = [...items.value, { id, message, type }];
+    setTimeout(() => dismiss(id), 4000);
+  }
+
+  function dismiss(id: number) {
+    items.value = items.value.filter((t) => t.id !== id);
+  }
+
+  return { items, show, dismiss };
+});

package/src/tokens.css

@@ -0,0 +1,159 @@
+/* @karyl-chan/ui — design tokens.
+ * Import once from your app entry: `import "@karyl-chan/ui/tokens.css"`.
+ *
+ * Theme model:
+ *   - Light tokens are the :root defaults.
+ *   - Dark tokens apply when EITHER the OS reports prefers-color-scheme: dark
+ *     AND no explicit light override is set, OR the consumer forces dark via
+ *     `data-theme="dark"` on <html>.
+ *   - `data-theme="light"` lets users opt out of system dark mode.
+ *   - `useColorScheme()` (composable) is the usual driver of that attribute,
+ *     including localStorage persistence; you can also set it yourself if
+ *     you want to roll your own controller.
+ *
+ * Bot-specific tokens (e.g. --conv-header-height, --spoiler-*) live in
+ * the bot frontend's own global.css alongside its own component styles.
+ */
+:root {
+    color-scheme: light dark;
+
+    --bg-page: #f9fafb;
+    --bg-surface: #ffffff;
+    --bg-surface-2: #f3f4f6;
+    --bg-surface-hover: rgba(0, 0, 0, 0.025);
+    --bg-surface-active: #eef2ff;
+    --bg-header: #1f2937;
+    --bg-overlay: rgba(0, 0, 0, 0.5);
+
+    --text: #111827;
+    --text-muted: #6b7280;
+    --text-strong: #111827;
+    --text-faint: #9ca3af;
+    --text-on-accent: #ffffff;
+    --text-on-header: #f9fafb;
+    --text-on-header-muted: #cbd5f5;
+
+    --border: #e5e7eb;
+    --border-strong: #d1d5db;
+
+    --accent: #5865f2;
+    --accent-bg: rgba(88, 101, 242, 0.15);
+    --accent-text: #5865f2;
+    --accent-text-strong: #4338ca;
+
+    --link: #2563eb;
+    --link-mask: #1d4ed8;
+
+    --danger: #b91c1c;
+
+    --success-bg: #d1fae5;
+    --success-text: #065f46;
+    --warn-bg: #fef3c7;
+    --warn-text: #92400e;
+
+    --code-bg: #f3f4f6;
+    --quote-border: #d1d5db;
+    --quote-text: #4b5563;
+
+    --pill-bg: #f3f4f6;
+
+    --transition-fast: 0.12s;
+    --transition-base: 0.15s;
+    --transition-slow: 0.2s;
+
+    --radius-sm: 4px;
+    --radius-base: 6px;
+    --radius-lg: 8px;
+    --radius-xl: 12px;
+    --radius-pill: 999px;
+}
+
+/* Pin the UA-side color-scheme hint so native widgets (form controls,
+ * scrollbars) follow the explicit choice instead of falling back to
+ * "light dark" and tracking the OS. */
+:root[data-theme="light"] { color-scheme: light; }
+:root[data-theme="dark"] { color-scheme: dark; }
+
+/* Dark tokens — applied in two situations:
+ *   1. System reports dark AND the user hasn't forced light.
+ *   2. The user has explicitly chosen dark (`data-theme="dark"`).
+ * Kept as a single selector list so the two paths can't drift. */
+@media (prefers-color-scheme: dark) {
+    :root:not([data-theme="light"]) {
+        --bg-page: #1e1f22;
+        --bg-surface: #2b2d31;
+        --bg-surface-2: #1e1f22;
+        --bg-surface-hover: rgba(255, 255, 255, 0.04);
+        --bg-surface-active: #3a3c44;
+        --bg-header: #18191c;
+
+        --text: #dbdee1;
+        --text-muted: #a3a6aa;
+        --text-strong: #f2f3f5;
+        --text-faint: #80848e;
+        --text-on-header: #f2f3f5;
+        --text-on-header-muted: #b5bac1;
+
+        --border: #3f4248;
+        --border-strong: #4e5058;
+
+        --accent-bg: rgba(88, 101, 242, 0.25);
+        --accent-text: #a5b4fc;
+        --accent-text-strong: #c7d2fe;
+
+        --link: #93c5fd;
+        --link-mask: #bfdbfe;
+
+        --danger: #f87171;
+
+        --success-bg: #064e3b;
+        --success-text: #a7f3d0;
+        --warn-bg: #78350f;
+        --warn-text: #fef3c7;
+
+        --code-bg: #1e1f22;
+        --quote-border: #4e5058;
+        --quote-text: #b5bac1;
+
+        --pill-bg: #313338;
+    }
+}
+
+:root[data-theme="dark"] {
+    --bg-page: #1e1f22;
+    --bg-surface: #2b2d31;
+    --bg-surface-2: #1e1f22;
+    --bg-surface-hover: rgba(255, 255, 255, 0.04);
+    --bg-surface-active: #3a3c44;
+    --bg-header: #18191c;
+
+    --text: #dbdee1;
+    --text-muted: #a3a6aa;
+    --text-strong: #f2f3f5;
+    --text-faint: #80848e;
+    --text-on-header: #f2f3f5;
+    --text-on-header-muted: #b5bac1;
+
+    --border: #3f4248;
+    --border-strong: #4e5058;
+
+    --accent-bg: rgba(88, 101, 242, 0.25);
+    --accent-text: #a5b4fc;
+    --accent-text-strong: #c7d2fe;
+
+    --link: #93c5fd;
+    --link-mask: #bfdbfe;
+
+    --danger: #f87171;
+
+    --success-bg: #064e3b;
+    --success-text: #a7f3d0;
+    --warn-bg: #78350f;
+    --warn-text: #fef3c7;
+
+    --code-bg: #1e1f22;
+    --quote-border: #4e5058;
+    --quote-text: #b5bac1;
+
+    --pill-bg: #313338;
+}