@tunji_xy/ui 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Olatunji Ekisanya
+
+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

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# @tunji_xy/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A component library for Nuxt 4, built as a **Nuxt layer** and styled with **Tailwind CSS v4**.
+Extend it and every component is auto-imported with the `Ui` prefix (`<UiButton>`,
+`<UiSelect>`, `<UiModal>`, …), along with Tailwind and the library's design tokens.
+
+**Documentation** for theming and every component (live examples, props, keyboard support)
+lives in the docs site in this repo: clone it, run `npm install` and `npm run dev`, and open
+http://localhost:3000.
+
+## Quick start
+
+```bash
+npm install @tunji_xy/ui
+```
+
+Then extend the layer:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: ["@tunji_xy/ui"],
+});
+```
+
+The layer brings Tailwind with it, so don't install or configure Tailwind again in the app.
+For icons, add `@lucide/vue`, which is what the components use themselves.
+
+## Requirements
+
+- Node.js 20.19+
+- **npm 11+.** npm 10 (bundled with Node 22) crashes on install with
+  `Cannot read properties of null (reading 'edgesOut')`. Upgrade once with
+  `npm install -g npm@11`.
+
+## Developing
+
+```bash
+npm install
+npm run dev          # docs site at http://localhost:3000, hot-reloads component edits
+npm run typecheck    # vue-tsc across the docs site + components
+npm run build        # production build of the docs site
+npm run generate     # static docs site in .playground/.output/public
+```
+
+```
+component-ui/
+├─ app/
+│  ├─ components/        one .vue file per component
+│  ├─ assets/css/        main.css (Tailwind import, design tokens, dark theme)
+│  └─ lib/cn.ts          class merging helper (tailwind-merge)
+├─ .playground/          the docs site, which extends the layer like any app
+└─ nuxt.config.ts        registers components ("Ui" prefix) and the Tailwind Vite plugin
+```
+
+## Adding a component
+
+1. Create `app/components/Thing.vue`. It's available everywhere as `<UiThing>`.
+2. Import Vue APIs explicitly (`import { ref } from 'vue'`) and `cn` from `../lib/cn`.
+3. Style it with token utilities (`bg-primary`, `border-border`, …), never hard-coded colours
+   like `bg-indigo-600`, so re-branding and dark mode reach it.
+4. Accept a `class` and merge it with `cn(...)` (see `Button.vue`).
+5. Document it in the docs site:
+   - an entry in `.playground/app/docs/components.ts` (sidebar and component cards)
+   - a props playground in `.playground/app/demo/ThingDemo.vue`
+   - examples in `.playground/app/examples/thing/`
+   - a page at `.playground/app/pages/components/thing.vue` (copy an existing one)
+6. Bump the version (semver: breaking prop changes mean a major bump) and add an entry to
+   `CHANGELOG.md`.

package/app/assets/css/main.css

@@ -0,0 +1,193 @@
+@import "tailwindcss";
+
+/*
+ * Tailwind skips node_modules when scanning for classes. When this layer is
+ * installed as a package, this line makes sure the classes used by its own
+ * components are still generated. (The app's own files are scanned automatically.)
+ */
+@source "../../components";
+
+/* Dark mode follows a "dark" class on <html> (works with @nuxtjs/color-mode). */
+@custom-variant dark (&:where(.dark, .dark *));
+
+/*
+ * Design tokens. Each one becomes a Tailwind utility, e.g. --color-primary gives
+ * bg-primary / text-primary / border-primary / ring-primary, and --radius-control
+ * gives rounded-control. Apps that extend this layer can use them too.
+ *
+ * To re-brand in an app, override the variables in the app's CSS:
+ *   :root { --color-primary: #0f766e; --color-primary-hover: #115e59; }
+ */
+@theme {
+  /* Brand */
+  --color-primary: #4f46e5;
+  --color-primary-hover: #4338ca;
+  --color-primary-foreground: #ffffff;
+  --color-danger: #dc2626;
+  --color-danger-hover: #b91c1c;
+  --color-danger-foreground: #ffffff;
+
+  /* Surfaces & text */
+  --color-background: #f4f4f5;
+  --color-surface: #ffffff;
+  --color-muted: #f4f4f5;
+  --color-foreground: #18181b;
+  --color-muted-foreground: #52525b;
+  --color-border: #d4d4d8;
+  --color-border-strong: #a1a1aa;
+  --color-overlay: rgb(9 9 11 / 0.55);
+
+  /* Shape */
+  --radius-control: 0.5rem; /* buttons, inputs */
+  --radius-panel: 0.875rem; /* modals, cards */
+
+  /* Motion */
+  --animate-modal-in: ui-modal-in 300ms cubic-bezier(0.32, 0.72, 0, 1);
+  --animate-modal-out: ui-modal-out 200ms ease-in forwards;
+  --animate-fade-in: ui-fade-in 180ms ease-out;
+  --animate-fade-out: ui-fade-out 200ms ease-in forwards;
+  --animate-caret-blink: ui-caret-blink 1s step-end infinite;
+  --animate-progress-indeterminate: ui-progress-indeterminate 1.4s ease-in-out
+    infinite;
+
+  /* UiModal sets where these slide from (see the UiModal section below). */
+  @keyframes ui-modal-in {
+    from {
+      opacity: var(--ui-modal-opacity-from, 0);
+      translate: var(--ui-modal-slide-from, 0 2rem);
+    }
+  }
+  @keyframes ui-modal-out {
+    to {
+      opacity: var(--ui-modal-opacity-from, 0);
+      translate: var(--ui-modal-slide-from, 0 2rem);
+    }
+  }
+  @keyframes ui-fade-in {
+    from {
+      opacity: 0;
+    }
+  }
+  @keyframes ui-fade-out {
+    to {
+      opacity: 0;
+    }
+  }
+  @keyframes ui-caret-blink {
+    50% {
+      opacity: 0;
+    }
+  }
+  /* A 40%-wide segment, from just off the left edge to just off the right. */
+  @keyframes ui-progress-indeterminate {
+    from {
+      translate: -100%;
+    }
+    to {
+      translate: 250%;
+    }
+  }
+}
+
+.dark {
+  --color-primary: #818cf8;
+  --color-primary-hover: #a5b4fc;
+  --color-primary-foreground: #11111b;
+  --color-danger: #f87171;
+  --color-danger-hover: #fca5a5;
+  --color-danger-foreground: #1c0a0a;
+
+  --color-background: #09090b;
+  --color-surface: #18181b;
+  --color-muted: #27272a;
+  --color-foreground: #fafafa;
+  --color-muted-foreground: #a1a1aa;
+  --color-border: #3f3f46;
+  --color-border-strong: #52525b;
+  --color-overlay: rgb(0 0 0 / 0.7);
+}
+
+/*
+ * UiModal: a sheet along the bottom of the screen on phones, centred from the
+ * sm breakpoint (640px) up, and the whole screen with size="full".
+ *
+ * These rules are in the components layer, so a class passed to <UiModal> wins
+ * over them at every screen size: class="max-w-xl", or the docs site's
+ * class="m-0 h-dvh w-72" side drawer.
+ *
+ * It slides in from --ui-modal-slide-from (a translate value, relative to its
+ * own size), starting at --ui-modal-opacity-from. A side drawer can set both:
+ * class="[--ui-modal-slide-from:-100%_0] [--ui-modal-opacity-from:1]".
+ */
+@layer components {
+  dialog[data-ui-modal] {
+    --ui-modal-slide-from: 0 100%;
+    --ui-modal-opacity-from: 1;
+    /* Tailwind's reset removes the browser's auto margins. Auto above pins it to the bottom. */
+    margin: auto auto 0;
+    width: 100%;
+    max-width: none;
+    max-height: calc(100dvh - 2rem);
+    border-radius: var(--radius-panel) var(--radius-panel) 0 0;
+
+    @variant sm {
+      --ui-modal-slide-from: 0 2rem;
+      --ui-modal-opacity-from: 0;
+      margin: auto;
+      width: calc(100% - 2rem);
+      max-height: calc(100dvh - 4rem);
+      border-radius: var(--radius-panel);
+
+      &[data-size="sm"] {
+        max-width: 24rem;
+      }
+      &[data-size="md"] {
+        max-width: 32rem;
+      }
+      &[data-size="lg"] {
+        max-width: 48rem;
+      }
+    }
+
+    &[data-size="full"] {
+      --ui-modal-slide-from: 0 100%;
+      --ui-modal-opacity-from: 1;
+      margin: 0;
+      width: 100%;
+      height: 100dvh;
+      max-width: none;
+      max-height: none;
+      border-radius: 0;
+    }
+
+    /* Modal.vue sets data-closing, then closes the dialog once the animation ends. */
+    &[open] {
+      animation: var(--animate-modal-in);
+      &::backdrop {
+        animation: var(--animate-fade-in);
+      }
+    }
+    &[data-closing] {
+      animation: var(--animate-modal-out);
+      pointer-events: none;
+      &::backdrop {
+        animation: var(--animate-fade-out);
+      }
+    }
+
+    /* With reduced motion, it fades in place instead of sliding. */
+    @variant motion-reduce {
+      &[open] {
+        animation: var(--animate-fade-in);
+      }
+      &[data-closing] {
+        animation: var(--animate-fade-out);
+      }
+    }
+  }
+}
+
+/* Stop the page behind an open UiModal from scrolling. */
+html:has(dialog[data-ui-modal][open]) {
+  overflow: hidden;
+}

package/app/components/Button.vue

@@ -0,0 +1,126 @@
+<template>
+  <button
+    v-bind="passthroughAttrs"
+    :type="type"
+    :class="classes"
+    :disabled="disabled"
+    :aria-busy="loading || undefined"
+    @click="onClick"
+  >
+    <span
+      v-if="loading"
+      class="size-4 animate-spin rounded-full border-2 border-current border-r-transparent"
+      aria-hidden="true"
+    />
+    <span v-else-if="$slots.leading" class="inline-flex text-[1.1em]">
+      <slot name="leading" />
+    </span>
+    <span>
+      <slot />
+    </span>
+    <span v-if="$slots.trailing" class="inline-flex text-[1.1em]">
+      <slot name="trailing" />
+    </span>
+  </button>
+</template>
+
+<script setup lang="ts">
+import { computed, useAttrs } from "vue";
+import { cn } from "../lib/cn";
+
+export interface ButtonProps {
+  variant?: "primary" | "outline" | "ghost" | "danger" | "text";
+  size?: "sm" | "md" | "lg";
+  type?: "button" | "submit" | "reset";
+  disabled?: boolean;
+  loading?: boolean;
+  block?: boolean;
+  raised?: boolean;
+  radius?: "none" | "sm" | "md" | "lg" | "full";
+}
+
+const props = withDefaults(defineProps<ButtonProps>(), {
+  variant: "primary",
+  size: "md",
+  type: "button",
+  disabled: false,
+  loading: false,
+  block: false,
+  raised: false,
+  radius: "none",
+});
+
+const emit = defineEmits<{
+  click: [event: MouseEvent];
+}>();
+
+defineSlots<{
+  /** Button label. */
+  default?: () => unknown;
+  /** Icon before the label (hidden while loading). */
+  leading?: () => unknown;
+  /** Icon after the label. */
+  trailing?: () => unknown;
+}>();
+
+// We merge the app's `class` ourselves so it can override defaults (e.g. class="px-8").
+defineOptions({ inheritAttrs: false });
+const attrs = useAttrs();
+
+const base =
+  "inline-flex shrink-0 cursor-pointer items-center justify-center gap-2 whitespace-nowrap " +
+  "border border-transparent font-semibold leading-none select-none outline-none transition-colors " +
+  "focus-visible:ring-3 focus-visible:ring-primary/35 disabled:cursor-not-allowed disabled:opacity-50";
+
+const variants = {
+  primary: "bg-primary text-primary-foreground hover:bg-primary-hover",
+  outline: "border-primary bg-transparent text-primary hover:bg-primary/10",
+  ghost: "bg-primary/10 text-primary border-transparent hover:bg-primary/20",
+  danger:
+    "bg-danger text-danger-foreground hover:bg-danger-hover focus-visible:ring-danger/35",
+  text: "text-foreground bg-transparent",
+} as const;
+
+const sizes = {
+  sm: "h-8 px-3 text-sm",
+  md: "h-10 px-4 text-sm",
+  lg: "h-12 px-6 text-base",
+} as const;
+
+const radii = {
+  none: "rounded-none",
+  sm: "rounded-sm",
+  md: "rounded-md",
+  lg: "rounded-lg",
+  full: "rounded-full",
+} as const;
+
+const raised =
+  "shadow-sm transition hover:shadow-md enabled:active:translate-y-px enabled:active:shadow-none";
+
+const classes = computed(() =>
+  cn(
+    base,
+    variants[props.variant],
+    sizes[props.size],
+    props.block && "flex w-full",
+    props.raised && raised,
+    radii[props.radius],
+    props.loading && "cursor-progress",
+    attrs.class as string,
+  ),
+);
+
+const passthroughAttrs = computed(() => {
+  const { class: _class, ...rest } = attrs;
+  return rest;
+});
+
+const onClick = (event: MouseEvent) => {
+  if (props.disabled || props.loading) {
+    event.preventDefault();
+    return;
+  }
+  emit("click", event);
+};
+</script>

package/app/components/Checkbox.vue

@@ -0,0 +1,130 @@
+<template>
+  <div
+    :class="cn('flex flex-col gap-1 text-foreground', attrs.class as string)"
+  >
+    <div
+      :class="
+        cn(
+          'flex items-start',
+          sizes[size].row,
+          disabled && 'cursor-not-allowed opacity-60',
+        )
+      "
+    >
+      <span class="relative flex h-lh shrink-0 items-center">
+        <input
+          :id="inputId"
+          ref="input"
+          v-model="model"
+          v-bind="inputAttrs"
+          type="checkbox"
+          :class="boxClasses"
+          :name="name"
+          :value="value"
+          :disabled="disabled"
+          :required="required"
+          :aria-describedby="message ? messageId : undefined"
+        />
+        <CheckIcon
+          :class="
+            cn(
+              'pointer-events-none absolute inset-0 m-auto text-white opacity-0 transition-opacity peer-checked:opacity-100',
+              sizes[size].check,
+            )
+          "
+          :stroke-width="3"
+        />
+      </span>
+
+      <label
+        v-if="label || $slots.default"
+        :for="inputId"
+        :class="
+          cn('select-none', disabled ? 'cursor-not-allowed' : 'cursor-pointer')
+        "
+      >
+        <slot>{{ label }}</slot>
+      </label>
+    </div>
+
+    <p
+      v-if="message"
+      :id="messageId"
+      :class="cn('text-sm', sizes[size].message, 'text-muted-foreground')"
+    >
+      {{ message }}
+    </p>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, useAttrs, useId, useTemplateRef } from "vue";
+import { CheckIcon } from "@lucide/vue";
+import { cn } from "../lib/cn";
+
+export interface CheckboxProps {
+  label?: string;
+  hint?: string;
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  required?: boolean;
+  id?: string;
+  name?: string;
+  /** Added to / removed from the v-model when it's an array. */
+  value?: string | number;
+}
+
+const props = withDefaults(defineProps<CheckboxProps>(), {
+  size: "md",
+});
+
+// A boolean for a single checkbox, or an array of the checked `value`s for a group.
+const model = defineModel<boolean | (string | number)[]>({ default: false });
+
+defineSlots<{
+  /** Label content, when it needs more than plain text (e.g. a link). */
+  default?: () => unknown;
+}>();
+
+// `class` styles the outer wrapper; every other attribute and listener
+// (@change, @focus, data-*) goes to the <input> itself.
+defineOptions({ inheritAttrs: false });
+const attrs = useAttrs();
+const inputAttrs = computed(() => {
+  const { class: _class, ...rest } = attrs;
+  return rest;
+});
+
+const autoId = useId();
+const inputId = computed(() => props.id ?? `ui-checkbox-${autoId}`);
+const messageId = computed(() => `${inputId.value}-message`);
+const message = computed(() => props.hint);
+
+// Lucide's check spans two thirds of its grid, so it's drawn smaller than the
+// box to leave a margin, with a heavier stroke to keep it legible at that size.
+const sizes = {
+  sm: { row: "gap-2 text-sm", box: "size-4", check: "size-3", message: "pl-6" },
+  md: { row: "gap-2 text-sm", box: "size-5", check: "size-3.5", message: "pl-7" },
+  lg: { row: "gap-3 text-base", box: "size-6", check: "size-4", message: "pl-9" },
+} as const;
+
+// The native input is restyled into the box, so keyboard, forms and
+// screen readers behave exactly like a plain checkbox.
+const boxClasses = computed(() =>
+  cn(
+    "peer m-0 cursor-pointer appearance-none rounded-sm border border-border bg-transparent outline-none " +
+      "transition-[background-color,border-color,box-shadow] checked:border-primary checked:bg-primary " +
+      "focus-visible:ring-3 disabled:cursor-not-allowed",
+    sizes[props.size].box,
+    "focus-visible:ring-primary/35",
+    !props.disabled && "not-checked:hover:border-border-strong",
+  ),
+);
+
+const inputEl = useTemplateRef<HTMLInputElement>("input");
+
+defineExpose({
+  focus: () => inputEl.value?.focus(),
+  el: inputEl,
+});
+</script>