@finema/core 2.29.0 → 2.31.0

package/README.md

@@ -1,79 +1,410 @@
-<!--
-Get your module up and running quickly.
-
-Find and replace all on all files (CMD+SHIFT+F):
-- Name: Finema UI Kit (Note: package.json has name: @finema/core, consider aligning these)
-- Package name: @finema/core
-- Description: A comprehensive UI kit for Finema projects.
--->
-
-# Finema UI Kit
-
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![License][license-src]][license-href]
-[![Nuxt][nuxt-src]][nuxt-href]
-
-A comprehensive UI kit for building consistent and beautiful user interfaces for Finema projects, designed to integrate seamlessly with Nuxt. This package is named `@finema/core` on npm.
-
-- [✨ &nbsp;Release Notes](/CHANGELOG.md)
-- [📖 &nbsp;Storybook](https://your-storybook-url.com) <!-- Add a link to your Storybook -->
-- [🕹️ &nbsp;Playground](#playground)
-
-## Features
-
-<!-- Highlight some of the features your UI kit provides here -->
-- 🎨 &nbsp;Wide range of customizable components, built for Vue and Nuxt
-- 📱 &nbsp;Responsive design out-of-the-box
-- ♿ &nbsp;Accessibility focused
-- 🛠️ &nbsp;Easy to integrate and use with Nuxt auto-import capabilities
-
-## 🚀 Installation
-
-Install the UI kit in your project using npm or yarn:
-
-```bash
-npm install @finema/core
-```
-
-or
-
-```bash
-yarn add @finema/core
-```
-
-## 🛠️ Available Scripts
-
-In the project directory, you can run the following scripts:
-
-- `npm run dev` or `yarn dev`: Runs the playground app in development mode.
-- `npm run dev:build` or `yarn dev:build`: Builds the playground app.
-- `npm run dev:prepare` or `yarn dev:prepare`: Prepares the development environment.
-- `npm run lint` or `yarn lint`: Lints the codebase.
-- `npm run test` or `yarn test`: Runs tests.
-- `npm run release` or `yarn release`: Creates a new release (lints, tests, builds, publishes).
-
-## 🕹️ Playground
-
-This project includes a `playground` directory that you can use to test and experiment with the UI components.
-
-To run the playground:
-1. Navigate to the `playground` directory.
-2. Install dependencies if you haven't already (`npm install` or `yarn install`).
-3. Run `npm run dev` or `yarn dev`.
-
-## 🤝 Contributing
-
-Contributions are welcome! Please refer to the `CONTRIBUTING.md` file for guidelines. (You'll need to create this file).
-
-<!--
-Badge URLs - Keep these at the bottom of the file for better readability
--->
-[npm-version-src]: https://img.shields.io/npm/v/@finema/core.svg
-[npm-version-href]: https://npmjs.com/package/@finema/core
-[npm-downloads-src]: https://img.shields.io/npm/dm/@finema/core.svg
-[npm-downloads-href]: https://npmjs.com/package/@finema/core
-[license-src]: https://img.shields.io/npm/l/@finema/core.svg
-[license-href]: https://npmjs.com/package/@finema/core
-[nuxt-src]: https://img.shields.io/badge/Nuxt-00DC82?logo=nuxt.js
-[nuxt-href]: https://nuxt.com
+# @finema/core
+
+[![bun version][bun-version-src]][bun-version-href]
+[![bun downloads][bun-downloads-src]][bun-downloads-href]
+[![License][license-src]][license-href]
+[![Nuxt][nuxt-src]][nuxt-href]
+
+> Enterprise-grade Vue.js UI component library for Nuxt applications
+
+A comprehensive, production-ready UI kit that provides 20+ auto-registered components, composables, and utilities for building consistent and beautiful user interfaces. Designed specifically for Nuxt 3 with TypeScript support, automatic validation, and seamless theming.
+
+## ✨ Features
+
+- 🎨 **20+ Auto-registered Components** - Forms, tables, dialogs, loaders, and more
+- 🔧 **Auto-imported Composables** - Dialog, notifications, form helpers, data loaders
+- ✅ **Integrated Validation** - vee-validate + valibot with Thai localization
+- 🎭 **Theming System** - Built on @nuxt/ui and Tailwind CSS
+- 📦 **Quality-of-life Features** - Lodash auto-imports, masked inputs, and more
+- 📱 **Mobile-first Design** - Responsive components out-of-the-box
+- ♿ **Accessibility Focused** - ARIA labels, keyboard navigation, screen reader support
+- ⚡ **Performance Optimized** - Tree-shaking, lazy loading, virtual scrolling
+- 🔒 **Type Safe** - Full TypeScript support with auto-generated types
+
+## 📋 Quick Links
+
+- [📖 Getting Started Guide](./docs/getting-started.md) - Complete setup and usage guide
+- [🎮 Playground Examples](./playground/) - Live examples and demos
+- [📚 Component Documentation](./docs/components/) - Detailed component API
+- [🔧 Composables Guide](./docs/composables/) - Available utilities and helpers
+- [🎨 Theming Guide](./docs/theming.md) - Customize colors and styling
+- [✨ Release Notes](./CHANGELOG.md) - What's new in each version
+
+## 🚀 Installation
+
+### Prerequisites
+- **Nuxt 3** (Vue 3, Vite)
+- **Node.js 22+** (recommended)
+
+### Install Package
+
+```bash
+# bun
+bun install @finema/core
+
+# yarn
+yarn add @finema/core
+
+# pnpm
+pnpm add @finema/core
+```
+
+### Setup Module
+
+Add the module to your `nuxt.config.ts`:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '@finema/core'
+  ]
+})
+```
+
+That's it! All components and composables are now auto-imported and ready to use.
+
+## 🎯 Quick Start
+
+### Simple Form Example
+
+```vue
+<template>
+  <div class="max-w-md mx-auto p-6">
+    <h1 class="text-2xl font-bold mb-6">Contact Form</h1>
+
+    <Form @submit="onSubmit">
+      <FormFields :options="formFields" />
+
+      <Button type="submit" :loading="isSubmitting" class="mt-6">
+        Submit
+      </Button>
+    </Form>
+  </div>
+</template>
+
+<script setup lang="ts">
+// Form validation schema using valibot
+const form = useForm({
+  validationSchema: toTypedSchema(
+    v.object({
+      name: v.pipe(v.string(), v.minLength(2)),
+      email: v.pipe(v.string(), v.email()),
+      message: v.pipe(v.string(), v.minLength(10))
+    })
+  )
+})
+
+// Form fields configuration
+const formFields = createFormFields(() => [
+  {
+    type: INPUT_TYPES.TEXT,
+    props: {
+      name: 'name',
+      label: 'Full Name',
+      required: true
+    }
+  },
+  {
+    type: INPUT_TYPES.TEXT,
+    props: {
+      name: 'email',
+      label: 'Email',
+      type: 'email',
+      required: true
+    }
+  },
+  {
+    type: INPUT_TYPES.TEXTAREA,
+    props: {
+      name: 'message',
+      label: 'Message',
+      rows: 4,
+      required: true
+    }
+  }
+])
+
+const isSubmitting = ref(false)
+const notification = useNotification()
+
+const onSubmit = form.handleSubmit(async (values) => {
+  isSubmitting.value = true
+
+  try {
+    await $fetch('/api/contact', {
+      method: 'POST',
+      body: values
+    })
+
+    notification.success({
+      title: 'Success!',
+      description: 'Your message has been sent.'
+    })
+
+    form.resetForm()
+  } catch (error) {
+    notification.error({
+      title: 'Error',
+      description: 'Failed to send message.'
+    })
+  } finally {
+    isSubmitting.value = false
+  }
+}, moveToError)
+</script>
+```
+
+### Data Table Example
+
+```vue
+<template>
+  <div class="space-y-6">
+    <div class="flex justify-between items-center">
+      <h1 class="text-2xl font-bold">Users</h1>
+      <Button @click="refreshData">Refresh</Button>
+    </div>
+
+    <Table
+      :options="tableOptions"
+      @pageChange="store.fetchPageChange"
+      @search="store.fetchSearch"
+    />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { COLUMN_TYPES } from '#core/components/Table/types'
+
+// Set up data store
+const store = usePageLoader({
+  url: '/api/users',
+  transform: (response) => response.data
+})
+
+// Configure table
+const tableOptions = useTable({
+  repo: store,
+  options: {
+    isEnabledSearch: true
+  },
+  columns: () => [
+    {
+      accessorKey: 'name',
+      header: 'Name'
+    },
+    {
+      accessorKey: 'email',
+      header: 'Email',
+      type: COLUMN_TYPES.TEXT,
+      meta: { max: 30 }
+    },
+    {
+      accessorKey: 'avatar',
+      header: 'Avatar',
+      type: COLUMN_TYPES.IMAGE
+    },
+    {
+      accessorKey: 'createdAt',
+      header: 'Created',
+      type: COLUMN_TYPES.DATE_TIME
+    }
+  ]
+})
+
+// Load initial data
+onMounted(() => {
+  store.fetchPage()
+})
+
+const refreshData = () => {
+  store.fetchPage()
+}
+</script>
+```
+
+### Dialog and Notification Example
+
+```vue
+<template>
+  <div class="space-y-4">
+    <Button @click="showDialog">Show Dialog</Button>
+    <Button @click="showNotification">Show Notification</Button>
+  </div>
+</template>
+
+<script setup lang="ts">
+const dialog = useDialog()
+const notification = useNotification()
+
+const showDialog = async () => {
+  const confirmed = await dialog.confirm({
+    title: 'Confirm Action',
+    description: 'Are you sure you want to proceed?',
+    confirmText: 'Yes, proceed',
+    cancelText: 'Cancel'
+  })
+
+  if (confirmed) {
+    notification.success({
+      title: 'Action Confirmed',
+      description: 'The action was completed successfully.'
+    })
+  }
+}
+
+const showNotification = () => {
+  notification.info({
+    title: 'Information',
+    description: 'This is an informational message.',
+    duration: 5000
+  })
+}
+</script>
+```
+
+## 🧩 Available Components
+
+### Form Components
+- **Form** - Main form wrapper with validation
+- **FormFields** - Dynamic field renderer
+- **Input Types** - Text, Number, Select, Date, File Upload, WYSIWYG, and more
+
+### Data Display
+- **Table** - Advanced data tables with sorting, pagination, and search
+- **FlexDeck** - Flexible grid layouts with pagination
+- **Image** - Optimized image component with loading states
+
+### Feedback
+- **Dialog** - Modal dialogs for confirmations and alerts
+- **Notification** - Toast notifications
+- **Loader** - Loading indicators
+- **Empty** - Empty state components
+
+### Layout
+- **App** - Application wrapper with global configuration
+
+## 🔧 Available Composables
+
+### UI Composables
+- **useDialog()** - Modal dialog management
+- **useNotification()** - Toast notification system
+- **useApp()** - Global app state management
+
+### Form Composables
+- **useForm()** - Form state and validation (vee-validate)
+- **createFormFields()** - Reactive field configuration
+- **moveToError()** - Navigate to validation errors
+
+### Data Loading
+- **usePageLoader()** - Server-side pagination and CRUD operations
+- **useListLoader()** - Client-side list operations
+- **useObjectLoader()** - Single object operations
+- **useTable()** - Table configuration and state
+
+### Configuration
+- **useCoreConfig()** - Access app configuration
+- **useUiConfig()** - Theme configuration utilities
+
+## 🎨 Theming
+
+The UI kit is built on top of @nuxt/ui and Tailwind CSS, providing extensive theming capabilities:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@finema/core'],
+
+  appConfig: {
+    core: {
+      site_name: 'My App',
+      color: '#3B82F6'
+    },
+    ui: {
+      colors: {
+        primary: 'blue',
+        secondary: 'gray'
+      }
+    }
+  }
+})
+```
+
+## 🕹️ Playground
+
+Explore live examples and experiment with components in the playground:
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd ui-kit
+
+# Install dependencies
+bun install
+
+# Run playground
+bun run dev
+```
+
+Visit the playground at different routes:
+- `/` - Component overview
+- `/form` - Form examples
+- `/table` - Table examples
+- `/dialog` - Dialog examples
+- `/notification` - Notification examples
+
+## 🛠️ Development Scripts
+
+```bash
+# Development
+bun run dev              # Run playground in development
+bun run dev:build        # Build playground
+bun run dev:prepare      # Prepare development environment
+
+# Quality
+bun run lint             # Lint codebase
+bun run lint:fix         # Fix linting issues
+bun run test             # Run tests
+bun run test:watch       # Run tests in watch mode
+bun run test:types       # Type checking
+
+# Release
+bun run release          # Create new release (lint, test, build, publish)
+```
+
+## 📚 Documentation
+
+- [📖 Getting Started](./docs/getting-started.md) - Complete setup guide
+- [📋 Form System](./docs/forms.md) - Comprehensive form building guide
+- [📊 Table System](./docs/tables.md) - Advanced table features and patterns
+- [🎨 Theming Guide](./docs/theming.md) - Customization and styling
+- [🔧 API Reference](./docs/components/) - Detailed component documentation
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our contributing guidelines for details on:
+
+- Code style and conventions
+- Development workflow
+- Testing requirements
+- Pull request process
+
+## 📄 License
+
+[MIT License](./LICENSE) - see the [LICENSE](./LICENSE) file for details.
+
+## 🏢 About Finema
+
+This UI kit is developed and maintained by the Finema Dev Core Team for building consistent, accessible, and beautiful user interfaces across all Finema projects.
+
+<!--
+Badge URLs - Keep these at the bottom of the file for better readability
+-->
+[bun-version-src]: https://img.shields.io/bun/v/@finema/core.svg
+[bun-version-href]: https://npmjs.com/package/@finema/core
+[bun-downloads-src]: https://img.shields.io/bun/dm/@finema/core.svg
+[bun-downloads-href]: https://npmjs.com/package/@finema/core
+[license-src]: https://img.shields.io/bun/l/@finema/core.svg
+[license-href]: https://npmjs.com/package/@finema/core
+[nuxt-src]: https://img.shields.io/badge/Nuxt-00DC82?logo=nuxt.js
+[nuxt-href]: https://nuxt.com

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@finema/core",
-  "version": "2.29.0",
+  "version": "2.31.0",
   "configKey": "core",
   "builder": {
     "@nuxt/module-builder": "1.0.2",

package/dist/module.mjs

@@ -4,7 +4,7 @@ import * as lodash from 'lodash-es';
 import * as theme from '../dist/runtime/theme/index.js';
 
 const name = "@finema/core";
-const version = "2.29.0";
+const version = "2.31.0";
 
 const nuxtAppOptions = {
   head: {

package/dist/runtime/components/Form/FieldWrapper.vue

@@ -1,17 +1,17 @@
 <template>
-  <FormField
-    :label="label"
-    :name="name"
-    :description="description"
-    :hint="hint"
-    :data-testid="name"
-    :help="help"
-    :error="errorMessage"
-    :required="!!required"
-    :ui="containerUi"
-  >
-    <slot />
-  </FormField>
+  <FormField
+    :label="label"
+    :name="name"
+    :description="description"
+    :hint="hint"
+    :data-testid="name"
+    :help="help"
+    :error="errorMessage"
+    :required="!!required"
+    :ui="containerUi"
+  >
+    <slot />
+  </FormField>
 </template>
 
 <script setup>

package/dist/runtime/components/Form/Fields.vue

@@ -1,22 +1,22 @@
 <template>
-  <div
+  <div
     :class="[theme.base({
   class: [$props.class, ui?.base]
-})]"
-  >
-    <component
-      :is="componentMap[option.type]?.component"
-      v-for="option in options.filter((item) => !item.isHide)"
-      :key="option.props.name"
-      :class="option.class"
-      :form="form"
+})]"
+  >
+    <component
+      :is="componentMap[option.type]?.component"
+      v-for="option in options.filter((item) => !item.isHide)"
+      :key="option.props.name"
+      :class="option.class"
+      :form="form"
       v-bind="{
   ...getFieldBinding(option),
   ...componentMap[option.type]?.props
-}"
-      v-on="option.on ?? {}"
-    />
-  </div>
+}"
+      v-on="option.on ?? {}"
+    />
+  </div>
 </template>
 
 <script setup>
@@ -29,8 +29,10 @@ import FormInputToggle from "./InputToggle/index.vue";
 import FormInputCheckbox from "./InputCheckbox/index.vue";
 import FormInputSelect from "./InputSelect/index.vue";
 import FormInputSelectMultiple from "./InputSelectMultiple/index.vue";
+import FormInputComponent from "./InputComponent/index.vue";
 import FormInputRadio from "./InputRadio/index.vue";
 import FormInputDateTime from "./InputDateTime/index.vue";
+import FormInputTime from "./InputTime/index.vue";
 import FormInputDateTimeRange from "./InputDateTimeRange/index.vue";
 import FormInputUploadDropzoneAuto from "./InputUploadDropzoneAuto/index.vue";
 import FormInputUploadDropzone from "./InputUploadDropzone/index.vue";
@@ -75,7 +77,10 @@ const componentMap = {
     props: {}
   },
   // For INPUT_TYPES.COMPONENT, it will use option.component directly from the template
-  [INPUT_TYPES.COMPONENT]: void 0,
+  [INPUT_TYPES.COMPONENT]: {
+    component: FormInputComponent,
+    props: {}
+  },
   // Add other INPUT_TYPES here if they have dedicated components not covered by option.component
   [INPUT_TYPES.NUMBER]: {
     component: FormInputNumber,
@@ -103,6 +108,10 @@ const componentMap = {
     component: FormInputDateTime,
     props: {}
   },
+  [INPUT_TYPES.TIME]: {
+    component: FormInputTime,
+    props: {}
+  },
   [INPUT_TYPES.DATE]: {
     component: FormInputDateTime,
     props: {

package/dist/runtime/components/Form/InputCheckbox/index.vue

@@ -1,22 +1,22 @@
 <template>
-  <FieldWrapper
-    v-bind="wrapperProps"
-    label=""
-    description=""
-  >
-    <Checkbox
-      :model-value="value"
-      :disabled="wrapperProps.disabled"
-      :name="name"
-      :label="label"
-      :description="description"
-      :required="required"
-      :variant="variant"
-      :indicator="indicator"
-      :ui="ui"
-      @update:modelValue="onChange"
-    />
-  </FieldWrapper>
+  <FieldWrapper
+    v-bind="wrapperProps"
+    label=""
+    description=""
+  >
+    <Checkbox
+      :model-value="value"
+      :disabled="wrapperProps.disabled"
+      :name="name"
+      :label="label"
+      :description="description"
+      :required="required"
+      :variant="variant"
+      :indicator="indicator"
+      :ui="ui"
+      @update:modelValue="onChange"
+    />
+  </FieldWrapper>
 </template>
 
 <script setup>

package/dist/runtime/components/Form/InputComponent/index.vue

@@ -0,0 +1,23 @@
+<template>
+  <component :is="props.component" :value="value" v-bind="props"/>
+</template>
+
+<script setup>
+const props = defineProps({
+  component: { type: null, required: true },
+  form: { type: Object, required: false },
+  name: { type: String, required: true },
+  errorMessage: { type: String, required: false },
+  label: { type: null, required: false },
+  description: { type: String, required: false },
+  hint: { type: String, required: false },
+  rules: { type: null, required: false },
+  autoFocus: { type: Boolean, required: false },
+  placeholder: { type: String, required: false },
+  disabled: { type: Boolean, required: false },
+  readonly: { type: Boolean, required: false },
+  required: { type: Boolean, required: false },
+  help: { type: String, required: false },
+  ui: { type: null, required: false }
+});
+</script>

package/dist/runtime/components/Form/InputComponent/index.vue.d.ts

@@ -0,0 +1,3 @@
+import type { IComponentFieldProps } from '#core/components/Form/InputComponent/types';
+declare const _default: import("vue").DefineComponent<IComponentFieldProps, void, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<IComponentFieldProps> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+export default _default;

package/dist/runtime/components/Form/InputComponent/types.d.ts

@@ -0,0 +1,6 @@
+import type { IFieldProps, IFormFieldBase, INPUT_TYPES } from '#core/components/Form/types';
+import type { DefineComponent } from 'vue';
+export interface IComponentFieldProps extends IFieldProps {
+    component: string | DefineComponent | any;
+}
+export type IComponentField = IFormFieldBase<INPUT_TYPES.COMPONENT, IComponentFieldProps, {}>;