hanap-labs

hanap-labs

Shared UI toolkit package for components, helpers, and composables.

Build

npm install
npm run build

Documentation Site

The repository also includes the Vue-powered documentation site with live component examples:

npm run dev
npm run build:site
npm run preview

Public Entrypoints

• Root entrypoint: hanap-labs
• Components entrypoint: hanap-labs/components
• Helpers entrypoint: hanap-labs/helpers
• Composables entrypoint: hanap-labs/composables
• Auto-import helper entrypoint: hanap-labs/auto-import

Consumption Modes

1) Manual Named Imports (Default)

Use named imports when you want explicit dependencies per file.

import { HLButton, objectToQueryParams, usePopup } from "hanap-labs";

You can also import by module group:

import { HLButton } from "hanap-labs/components";
import type { HLButtonProps } from "hanap-labs/components";
import { objectToQueryParams } from "hanap-labs/helpers";
import { usePopup } from "hanap-labs/composables";

2) Optional Auto-Import Integration

If a consumer app uses unplugin-vue-components and unplugin-auto-import, the toolkit exposes helper factories to wire components and composables in one place.

Install plugins in the consumer app:

npm install -D unplugin-vue-components unplugin-auto-import

Update the consumer app vite.config.ts:

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import Components from "unplugin-vue-components/vite";
import AutoImport from "unplugin-auto-import/vite";
import { createToolkitAutoImportOptions } from "hanap-labs/auto-import";

const toolkitAutoImport = createToolkitAutoImportOptions();

export default defineConfig({
  plugins: [
    vue(),
    Components({
      resolvers: toolkitAutoImport.components.resolvers,
    }),
    AutoImport({
      imports: toolkitAutoImport.composables.imports,
    }),
  ],
});

To scope auto-imports, pass selected names:

createToolkitAutoImportOptions({
  componentNames: ["HLButton"],
  composableNames: ["usePopup"],
});

Consumer Setup Checklist

Apply these steps in each consuming website:

1. Install hanap-labs.
2. Import toolkit styles once in your app entry:
   • import "hanap-labs/styles.css";
   • In Nuxt, add "hanap-labs/styles.css" to nuxt.config.ts under css.
3. Choose a mode:
   • Keep manual named imports (default).
   • Enable optional auto-import using the Vite plugin setup above.
4. Run the app build and confirm toolkit components/composables resolve correctly.

Global Overlay Setup (popup and notify)

The toolkit includes app-level overlay plugins:

• createPopupPlugin() for popup host mounting
• createNotifyPlugin() for toast/notify host mounting

Auto-mount (recommended)

Use auto-mount when you want the toolkit to create and mount hosts to document.body:

import { createApp } from "vue";
import App from "./App.vue";
import { createNotifyPlugin, createPopupPlugin } from "hanap-labs";

createApp(App).use(createPopupPlugin()).use(createNotifyPlugin()).mount("#app");

Manual mount target

Use manual targets when your app needs explicit host element control:

<div id="app"></div>
<div id="popup-root"></div>
<div id="notify-root"></div>

import { createApp } from "vue";
import App from "./App.vue";
import { createNotifyPlugin, createPopupPlugin } from "hanap-labs";

createApp(App)
  .use(createPopupPlugin({ mountId: "popup-root", autoMount: true }))
  .use(createNotifyPlugin({ mountId: "notify-root", autoMount: true }))
  .mount("#app");

Theming

The toolkit supports host-driven theming through CSS variables, plus .light / .dark mode.

Toolkit theme tokens are scoped to the .hanap-labs-theme (and .hanap-labs-font) class, so importing hanap-labs/styles.css does not overwrite your app :root styles.

1. Add hanap-labs-theme (and optionally hanap-labs-font) to a wrapper element in your app (often body, #app, or a layout root).
2. (Optional) Define host tokens in your app :root (and override them in .dark).
3. Toggle .dark on a parent element (usually html or body) to enable dark mode.

Example wrapper:

<body class="hanap-labs-theme hanap-labs-font">
  <div id="app"></div>
</body>

Example:

:root {
  --primary: #15803d;
  --secondary: #9fcb98;
  --danger: #dc2626;
}

.dark {
  --primary: #85bb65;
  --secondary: #3e5f4a;
  --danger: #f87171;
}

Global Theme CSS Custom Properties

All global theme tokens are available as CSS custom properties prefixed with --hanap-labs-.

Color Tokens

Surface Tokens

Border Tokens

Text Tokens

Typography Tokens

TanStack Vue Query Setup (useQuery)

The useQuery and useMutation composables require TanStack Vue Query (optional peer dependency) to be installed, then registered once.

npm install @tanstack/vue-query

In your app entry (e.g., main.ts):

import { createApp } from "vue";
import App from "./App.vue";
import { createQueryPlugin } from "hanap-labs";

createApp(App)
  .use(
    createQueryPlugin({
      queries: {
        staleTime: 1000 * 60 * 5,
      },
    }),
  )
  .mount("#app");

Without this setup, useQuery and useMutation will throw a runtime error in fresh consumer apps.