@tunji_xy/ui 0.0.0-stage → 0.10.0

package/app/components/Tooltip.vue

@@ -0,0 +1,292 @@
+<template>
+  <!-- display: contents, so wrapping the trigger never changes its layout. -->
+  <span
+    ref="wrapper"
+    class="contents"
+    @pointerover="onPointerover"
+    @pointerout="onPointerout"
+    @pointerdown="onPointerdown"
+    @focusin="onFocusin"
+    @focusout="onFocusout"
+  >
+    <slot />
+    <span
+      v-if="content || $slots.content"
+      :id="tooltipId"
+      ref="tooltip"
+      v-bind="tooltipAttrs"
+      popover="manual"
+      role="tooltip"
+      :class="tooltipClasses"
+      :style="{ maxWidth: toCss(maxWidth) }"
+    >
+      <slot name="content">{{ content }}</slot>
+      <span
+        v-if="arrow"
+        class="absolute size-2 -translate-x-1/2 -translate-y-1/2 rotate-45 bg-inherit"
+        :style="arrowStyle"
+        aria-hidden="true"
+      />
+    </span>
+  </span>
+</template>
+
+<script setup lang="ts">
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  useAttrs,
+  useId,
+  useTemplateRef,
+  watch,
+} from "vue";
+import { cn } from "../lib/cn";
+
+type Side = "top" | "right" | "bottom" | "left";
+
+export interface TooltipProps {
+  content?: string;
+  placement?: Side;
+  /** Milliseconds the pointer must rest on the trigger before it opens. */
+  delay?: 0 | 200 | 500;
+  arrow?: boolean;
+  maxWidth?: number | string;
+}
+
+const props = withDefaults(defineProps<TooltipProps>(), {
+  placement: "top",
+  delay: 0,
+  arrow: true,
+  maxWidth: 240,
+});
+
+defineSlots<{
+  /** The element the tooltip describes, e.g. a <UiButton>. */
+  default?: () => unknown;
+  /** Rich tooltip content, instead of the `content` text. */
+  content?: () => unknown;
+}>();
+
+// `class` and other attributes style the tooltip bubble itself.
+defineOptions({ inheritAttrs: false });
+const attrs = useAttrs();
+const tooltipAttrs = computed(() => {
+  const { class: _class, ...rest } = attrs;
+  return rest;
+});
+
+const tooltipId = `ui-tooltip-${useId()}`;
+const wrapperEl = useTemplateRef<HTMLSpanElement>("wrapper");
+const tooltipEl = useTemplateRef<HTMLSpanElement>("tooltip");
+
+const toCss = (value: number | string) =>
+  typeof value === "number" ? `${value}px` : value;
+
+const triggerEl = () => {
+  const first = wrapperEl.value?.firstElementChild;
+  return first && first !== tooltipEl.value ? (first as HTMLElement) : null;
+};
+
+// Screen readers read the tooltip when the trigger gets focus. The trigger
+// might wrap the focusable element, as <UiInput> does.
+const FOCUSABLE = "a[href], button, input, select, textarea, [tabindex]";
+const describe = () => {
+  const trigger = triggerEl();
+  const target = trigger?.matches(FOCUSABLE)
+    ? trigger
+    : (trigger?.querySelector(FOCUSABLE) ?? trigger);
+  if (!target) return;
+  const ids = (target.getAttribute("aria-describedby") ?? "")
+    .split(" ")
+    .filter(Boolean);
+  if (!ids.includes(tooltipId)) {
+    target.setAttribute("aria-describedby", [...ids, tooltipId].join(" "));
+  }
+};
+onMounted(describe);
+
+const open = ref(false);
+let timer: ReturnType<typeof setTimeout> | undefined;
+let pending: boolean | undefined;
+let keyboardFocus = false;
+
+// Moving across the trigger's children fires pointerover again, so an
+// open or close that's already on its way isn't restarted.
+const schedule = (value: boolean, delay: number) => {
+  if (pending === value) return;
+  clearTimeout(timer);
+  pending = undefined;
+  if (open.value === value) return;
+  if (!delay) {
+    open.value = value;
+    return;
+  }
+  pending = value;
+  timer = setTimeout(() => {
+    pending = undefined;
+    open.value = value;
+  }, delay);
+};
+
+// The tooltip is inside the wrapper, so hovering it keeps it open.
+const isInside = (node: EventTarget | null) =>
+  node instanceof Node && !!wrapperEl.value?.contains(node);
+
+const onPointerover = (event: PointerEvent) => {
+  if (event.pointerType !== "touch") schedule(true, props.delay);
+};
+
+// A short grace period lets the pointer cross the gap onto the tooltip.
+const onPointerout = (event: PointerEvent) => {
+  if (!isInside(event.relatedTarget) && !keyboardFocus) schedule(false, 100);
+};
+
+const onPointerdown = (event: PointerEvent) => {
+  if (tooltipEl.value?.contains(event.target as Node)) return;
+  keyboardFocus = false;
+  schedule(false, 0);
+};
+
+// Only keyboard focus opens it, so a click or tap doesn't leave it showing.
+const onFocusin = (event: FocusEvent) => {
+  if (!(event.target as Element).matches(":focus-visible")) return;
+  keyboardFocus = true;
+  schedule(true, 0);
+};
+
+const onFocusout = (event: FocusEvent) => {
+  if (isInside(event.relatedTarget)) return;
+  keyboardFocus = false;
+  schedule(false, 0);
+};
+
+const onKeydown = (event: KeyboardEvent) => {
+  if (event.key !== "Escape") return;
+  // Stops a <UiModal> around the trigger closing too.
+  event.preventDefault();
+  schedule(false, 0);
+};
+
+const EDGE = 8;
+const opposite = { top: "bottom", bottom: "top", left: "right", right: "left" } as const;
+const side = ref<Side>(props.placement);
+const arrowOffset = ref(0);
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.max(min, Math.min(value, max));
+
+// Sits on the `placement` side, or the opposite one when there's more room
+// there, and slides along the trigger to stay on screen. The arrow keeps
+// pointing at the trigger's centre.
+function position() {
+  const trigger = triggerEl();
+  const tooltip = tooltipEl.value;
+  if (!trigger || !tooltip) return;
+  // Measured at the top-left, where nothing squeezes its width.
+  tooltip.style.left = tooltip.style.top = "0px";
+  const rect = trigger.getBoundingClientRect();
+  const { offsetWidth: width, offsetHeight: height } = tooltip;
+  const { clientWidth: vw, clientHeight: vh } = document.documentElement;
+  const gap = props.arrow ? 10 : 6;
+  const room = {
+    top: rect.top,
+    bottom: vh - rect.bottom,
+    left: rect.left,
+    right: vw - rect.right,
+  };
+
+  let placed: Side = props.placement;
+  const vertical = placed === "top" || placed === "bottom";
+  if (
+    room[placed] < (vertical ? height : width) + gap + EDGE &&
+    room[opposite[placed]] > room[placed]
+  ) {
+    placed = opposite[placed];
+  }
+
+  const centerX = rect.left + rect.width / 2;
+  const centerY = rect.top + rect.height / 2;
+  const x = clamp(
+    vertical
+      ? centerX - width / 2
+      : placed === "left"
+        ? rect.left - gap - width
+        : rect.right + gap,
+    EDGE,
+    vw - width - EDGE,
+  );
+  const y = clamp(
+    vertical
+      ? placed === "top"
+        ? rect.top - gap - height
+        : rect.bottom + gap
+      : centerY - height / 2,
+    EDGE,
+    vh - height - EDGE,
+  );
+
+  tooltip.style.left = `${x}px`;
+  tooltip.style.top = `${y}px`;
+  side.value = placed;
+  // Kept clear of the rounded corners.
+  arrowOffset.value = vertical
+    ? clamp(centerX - x, 12, width - 12)
+    : clamp(centerY - y, 12, height - 12);
+}
+
+const arrowStyle = computed(() =>
+  side.value === "top" || side.value === "bottom"
+    ? {
+        left: `${arrowOffset.value}px`,
+        top: side.value === "top" ? "100%" : "0",
+      }
+    : {
+        top: `${arrowOffset.value}px`,
+        left: side.value === "left" ? "100%" : "0",
+      },
+);
+
+function stopTracking() {
+  window.removeEventListener("scroll", position, true);
+  window.removeEventListener("resize", position);
+  document.removeEventListener("keydown", onKeydown);
+}
+
+watch(
+  open,
+  (isOpen) => {
+    const tooltip = tooltipEl.value;
+    if (!tooltip) return;
+    if (isOpen) {
+      describe();
+      if (!tooltip.matches(":popover-open")) tooltip.showPopover();
+      position();
+      window.addEventListener("scroll", position, {
+        capture: true,
+        passive: true,
+      });
+      window.addEventListener("resize", position);
+      document.addEventListener("keydown", onKeydown);
+    } else {
+      if (tooltip.matches(":popover-open")) tooltip.hidePopover();
+      stopTracking();
+    }
+  },
+  { flush: "post" },
+);
+
+onBeforeUnmount(() => {
+  stopTracking();
+  clearTimeout(timer);
+});
+
+const tooltipClasses = computed(() =>
+  cn(
+    "inset-auto m-0 animate-fade-in overflow-visible rounded-md border-0 bg-foreground px-2.5 py-1.5 " +
+      "text-left text-xs leading-snug font-medium break-words text-background shadow-md motion-reduce:animate-none",
+    attrs.class as string,
+  ),
+);
+</script>

package/app/lib/cn.ts

@@ -0,0 +1,25 @@
+import { extendTailwindMerge } from 'tailwind-merge'
+
+/*
+ * Joins class names and resolves Tailwind conflicts, so a class passed by the
+ * app wins over the component's default: cn('px-4', 'px-8') -> 'px-8'.
+ */
+const twMerge = extendTailwindMerge({
+  extend: {
+    // Teach tailwind-merge about our custom radius tokens (rounded-control / rounded-panel).
+    theme: { radius: ['control', 'panel'] },
+  },
+})
+
+type ClassValue = string | false | null | undefined | ClassValue[] | Record<string, unknown>
+
+function toClassString(value: ClassValue): string {
+  if (!value) return ''
+  if (typeof value === 'string') return value
+  if (Array.isArray(value)) return value.map(toClassString).filter(Boolean).join(' ')
+  return Object.keys(value).filter(key => value[key]).join(' ')
+}
+
+export function cn(...inputs: ClassValue[]): string {
+  return twMerge(toClassString(inputs))
+}

package/nuxt.config.ts

@@ -0,0 +1,22 @@
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import tailwindcss from '@tailwindcss/vite'
+
+// Resolve paths relative to THIS layer, not to the app that extends it.
+const currentDir = dirname(fileURLToPath(import.meta.url))
+
+export default defineNuxtConfig({
+  // Every component in app/components is auto-imported with the "Ui" prefix:
+  // Button.vue -> <UiButton>, Input.vue -> <UiInput>, Modal.vue -> <UiModal>.
+  // To rename the prefix for your company, change it here.
+  components: [
+    { path: join(currentDir, 'app/components'), prefix: 'Ui' },
+  ],
+
+  // Tailwind + design tokens, loaded in every app that extends this layer.
+  css: [join(currentDir, 'app/assets/css/main.css')],
+
+  vite: {
+    plugins: [tailwindcss()],
+  },
+})

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@tunji_xy/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "description": "Shared Nuxt 4 component library (layer) styled with Tailwind CSS: Button, Input, Textarea, Select, Checkbox, Radio, Switch, OtpInput, Tooltip, ProgressBar, Tabs, DropdownMenu, Modal",
+  "license": "MIT",
+  "author": "Olatunji Ekisanya",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tunjixy/components-ui.git"
+  },
+  "homepage": "https://github.com/tunjixy/components-ui#readme",
+  "bugs": "https://github.com/tunjixy/components-ui/issues",
+  "keywords": [
+    "nuxt",
+    "nuxt-layer",
+    "vue",
+    "tailwindcss",
+    "components",
+    "ui"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./nuxt.config.ts",
+  "files": [
+    "app",
+    "nuxt.config.ts"
+  ],
+  "scripts": {
+    "dev": "nuxi dev .playground",
+    "build": "nuxi build .playground",
+    "generate": "nuxi generate .playground",
+    "preview": "nuxi preview .playground",
+    "typecheck": "nuxi typecheck .playground",
+    "prepare": "nuxi prepare .playground"
+  },
+  "dependencies": {
+    "@lucide/vue": "^1.70.0",
+    "@tailwindcss/vite": "^4.3.0",
+    "tailwind-merge": "^3.7.0",
+    "tailwindcss": "^4.3.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "nuxt": "^4.2.0",
+    "shiki": "^4.5.0",
+    "typescript": "^5.9.0",
+    "vue": "^3.5.0",
+    "vue-tsc": "^3.1.0"
+  },
+  "engines": {
+    "node": ">=20.19.0",
+    "npm": ">=11.0.0"
+  }
+}