hanap-labs 0.1.0

package/LICENSE

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

@@ -0,0 +1,190 @@
+# hanap-labs
+
+Shared UI toolkit package for components, helpers, and composables.
+
+## Build
+
+```bash
+npm install
+npm run build
+```
+
+## 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.
+
+```ts
+import { AHButton, formatLabel, usePopup } from "hanap-labs";
+```
+
+You can also import by module group:
+
+```ts
+import { AHButton } from "hanap-labs/components";
+import type { AHButtonProps } from "hanap-labs/components";
+import { formatLabel } 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:
+
+```bash
+npm install -D unplugin-vue-components unplugin-auto-import
+```
+
+Update the consumer app `vite.config.ts`:
+
+```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:
+
+```ts
+createToolkitAutoImportOptions({
+  componentNames: ["AHButton"],
+  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";`
+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`:
+
+```ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import {
+  createNotifyPlugin,
+  createPopupPlugin,
+} from "hanap-labs/components";
+
+createApp(App).use(createPopupPlugin()).use(createNotifyPlugin()).mount("#app");
+```
+
+### Manual mount target
+
+Use manual targets when your app needs explicit host element control:
+
+```html
+<div id="app"></div>
+<div id="popup-root"></div>
+<div id="notify-root"></div>
+```
+
+```ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import {
+  createNotifyPlugin,
+  createPopupPlugin,
+} from "hanap-labs/components";
+
+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 and `.dark` mode.
+
+1. Define theme tokens in your app `:root` and `.dark`.
+2. Toggle `.dark` on a parent element (usually `html` or `body`).
+3. Toolkit components consume those values automatically.
+
+Example:
+
+```css
+:root {
+  --button-primary: #15803d;
+  --button-primary-text: #ffffff;
+  --border-muted: #d8e0da;
+}
+
+.dark {
+  --button-primary: #85bb65;
+  --button-primary-text: #030712;
+  --border-muted: rgba(255, 255, 255, 0.1);
+}
+```
+
+## TanStack Vue Query Setup (`useQuery`)
+
+The `useQuery` composable requires TanStack Vue Query to be installed and configured in your app.
+
+```bash
+npm install @tanstack/vue-query
+```
+
+In your app entry (e.g., `main.ts`):
+
+```ts
+import { createApp } from "vue";
+import App from "./App.vue";
+import { VueQueryPlugin, QueryClient } from "@tanstack/vue-query";
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 1000 * 60 * 5,
+    },
+  },
+});
+
+createApp(App).use(VueQueryPlugin, { queryClient }).mount("#app");
+```
+
+Without this setup, `useQuery` will throw a runtime error in fresh consumer apps.

package/dist/auto-import/index.js

@@ -0,0 +1,40 @@
+//#region src/auto-import/index.ts
+var e = "anonghanap-toolkit", t = `${e}/components`, n = `${e}/composables`, r = [
+	"AHAvatar",
+	"AHBreadcrumb",
+	"AHButton",
+	"AHIcon",
+	"AHMenuAction",
+	"AHSelect",
+	"AHSkeleton",
+	"AHTabs",
+	"AHTable"
+], i = [
+	"useFloat",
+	"useNotify",
+	"usePopup",
+	"useQuery"
+];
+function a(e = [...r]) {
+	let n = new Set(e);
+	return {
+		type: "component",
+		resolve(e) {
+			if (n.has(e)) return {
+				name: e,
+				from: t
+			};
+		}
+	};
+}
+function o(e = [...i]) {
+	return [{ [n]: [...e] }];
+}
+function s(e = {}) {
+	return {
+		components: { resolvers: [a(e.componentNames ?? [...r])] },
+		composables: { imports: o(e.composableNames ?? [...i]) }
+	};
+}
+//#endregion
+export { o as createToolkitAutoImportModules, s as createToolkitAutoImportOptions, a as createToolkitComponentsResolver };