anicca-ui 1.0.0

package/dist/theme/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * AniccaTheme — Token overrides for the AniccaUI design system.
+ *
+ * Pass partial values to `AniccaThemeProvider` to rebrand components
+ * without touching CSS. Any token omitted keeps the library default.
+ */
+export interface AniccaTheme {
+    primary?: string;
+    primaryFg?: string;
+    primarySoft?: string;
+    success?: string;
+    successBg?: string;
+    danger?: string;
+    dangerBg?: string;
+    warning?: string;
+    warningBg?: string;
+    info?: string;
+    infoBg?: string;
+    surface?: string;
+    surfaceMuted?: string;
+    surfaceOverlay?: string;
+    surfaceDark?: string;
+    surfaceDark2?: string;
+    surfaceDarkFg?: string;
+    surfaceDarkFgMuted?: string;
+    border?: string;
+    borderStrong?: string;
+    borderDark?: string;
+    text?: string;
+    textMuted?: string;
+    textSubtle?: string;
+    radius?: string;
+    radiusSm?: string;
+    radiusLg?: string;
+    shadowSm?: string;
+    shadowMd?: string;
+    shadowLg?: string;
+}
+export declare const ANICCA_THEME_CSS_VAR_MAP: Record<keyof AniccaTheme, string>;

package/dist/utils/functions/index.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Creates a debounced version of a function that delays execution
+ * until after the specified delay has elapsed since the last call.
+ *
+ * @param fn - Function to debounce
+ * @param delay - Delay in milliseconds
+ * @returns Debounced function
+ *
+ * @example
+ * ```ts
+ * const debouncedSearch = aniccaDebounce((query) => search(query), 300)
+ * ```
+ */
+export declare function aniccaDebounce<T extends (...args: never[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Creates a throttled version of a function that executes
+ * at most once per specified time limit.
+ *
+ * @param fn - Function to throttle
+ * @param limit - Minimum interval in milliseconds
+ * @returns Throttled function
+ *
+ * @example
+ * ```ts
+ * const throttledScroll = aniccaThrottle(handleScroll, 200)
+ * ```
+ */
+export declare function aniccaThrottle<T extends (...args: never[]) => unknown>(fn: T, limit: number): (...args: Parameters<T>) => void;
+/**
+ * Truncates a string to the specified length and appends a suffix.
+ *
+ * @param str - String to truncate
+ * @param length - Maximum length before truncation
+ * @param suffix - Suffix to append (default: "...")
+ * @returns Truncated string
+ */
+export declare function aniccaTruncate(str: string, length: number, suffix?: string): string;
+/**
+ * Copies text to the clipboard using the Clipboard API with
+ * a fallback to execCommand for older browsers.
+ *
+ * @param text - Text to copy
+ * @returns Promise resolving to true on success, false on failure
+ */
+export declare function aniccaCopyToClipboard(text: string): Promise<boolean>;
+/**
+ * Converts a string to a URL-friendly slug.
+ *
+ * @param str - String to slugify
+ * @returns Slugified string
+ *
+ * @example
+ * ```ts
+ * aniccaSlugify('Hello World!') // "hello-world"
+ * ```
+ */
+export declare function aniccaSlugify(str: string): string;
+/**
+ * Capitalizes the first letter of a string and lowercases the rest.
+ *
+ * @param str - String to capitalize
+ * @returns Capitalized string
+ */
+export declare function aniccaCapitalize(str: string): string;
+/**
+ * Creates a deep clone of an object.
+ * Uses structuredClone if available, falls back to JSON serialization.
+ *
+ * @param obj - Object to clone
+ * @returns Deep clone of the object
+ */
+export declare function aniccaDeepClone<T>(obj: T): T;
+/**
+ * Flattens a nested object into a single-level object with dot-notation keys.
+ *
+ * @param obj - Object to flatten
+ * @param prefix - Key prefix for recursion
+ * @returns Flattened object
+ *
+ * @example
+ * ```ts
+ * aniccaFlattenObject({ a: { b: { c: 1 } } })
+ * // { 'a.b.c': 1 }
+ * ```
+ */
+export declare function aniccaFlattenObject(obj: Record<string, unknown>, prefix?: string): Record<string, unknown>;
+/**
+ * Groups an array of objects by a specified key.
+ *
+ * @param array - Array to group
+ * @param key - Key to group by
+ * @returns Object with grouped arrays
+ *
+ * @example
+ * ```ts
+ * aniccaGroupBy([{ role: 'admin', name: 'A' }, { role: 'user', name: 'B' }], 'role')
+ * // { admin: [{ role: 'admin', name: 'A' }], user: [{ role: 'user', name: 'B' }] }
+ * ```
+ */
+export declare function aniccaGroupBy<T>(array: T[], key: keyof T): Record<string, T[]>;
+/**
+ * Returns a new array with duplicates removed based on a key property.
+ * Keeps the first occurrence of each unique key value.
+ *
+ * @param array - Array to deduplicate
+ * @param key - Key to check for uniqueness
+ * @returns Deduplicated array
+ */
+export declare function aniccaUniqueBy<T>(array: T[], key: keyof T): T[];

package/dist/utils/hooks/useAniccaUtils/index.d.ts

@@ -0,0 +1,2 @@
+export { useAniccaUtils } from './useAniccaUtils';
+export type { UseAniccaUtilsReturn } from './useAniccaUtils';

package/dist/utils/hooks/useAniccaUtils/useAniccaUtils.d.ts

@@ -0,0 +1,40 @@
+import { aniccaDebounce, aniccaThrottle, aniccaTruncate, aniccaCopyToClipboard, aniccaSlugify, aniccaCapitalize, aniccaDeepClone, aniccaFlattenObject, aniccaGroupBy, aniccaUniqueBy } from '../../functions';
+
+/**
+ * Return type for useAniccaUtils hook.
+ */
+export interface UseAniccaUtilsReturn {
+    /** Create a debounced function */
+    debounce: typeof aniccaDebounce;
+    /** Create a throttled function */
+    throttle: typeof aniccaThrottle;
+    /** Truncate a string */
+    truncate: typeof aniccaTruncate;
+    /** Copy text to clipboard */
+    copyToClipboard: typeof aniccaCopyToClipboard;
+    /** Convert string to slug */
+    slugify: typeof aniccaSlugify;
+    /** Capitalize first letter */
+    capitalize: typeof aniccaCapitalize;
+    /** Deep clone an object */
+    deepClone: typeof aniccaDeepClone;
+    /** Flatten nested object */
+    flattenObject: typeof aniccaFlattenObject;
+    /** Group array by key */
+    groupBy: typeof aniccaGroupBy;
+    /** Remove duplicates by key */
+    uniqueBy: typeof aniccaUniqueBy;
+}
+/**
+ * useAniccaUtils — A hook that provides access to all utility functions
+ * as a memoized object for convenient use in React components.
+ *
+ * @returns Object containing all utility functions
+ *
+ * @example
+ * ```tsx
+ * const { slugify, truncate, copyToClipboard } = useAniccaUtils()
+ * const slug = slugify('Hello World')
+ * ```
+ */
+export declare function useAniccaUtils(): UseAniccaUtilsReturn;

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './functions';
+export * from './hooks/useAniccaUtils';

package/dist/validation/hooks/useAniccaForm/index.d.ts

@@ -0,0 +1,2 @@
+export { useAniccaForm } from './useAniccaForm';
+export type { UseAniccaFormConfig, UseAniccaFormReturn } from './useAniccaForm';

package/dist/validation/hooks/useAniccaForm/useAniccaForm.d.ts

@@ -0,0 +1,60 @@
+import { ValidationRule } from '../../rules';
+
+/**
+ * Configuration for useAniccaForm hook.
+ */
+export interface UseAniccaFormConfig<T extends Record<string, unknown>> {
+    /** Initial form values */
+    initialValues: T;
+    /** Validation schema mapping field names to validation rules */
+    validationSchema?: Partial<Record<keyof T, ValidationRule[]>>;
+    /** Submit handler called with valid form values */
+    onSubmit?: (values: T) => void | Promise<void>;
+}
+/**
+ * Return type for useAniccaForm hook.
+ */
+export interface UseAniccaFormReturn<T extends Record<string, unknown>> {
+    /** Current form values */
+    values: T;
+    /** Current field errors */
+    errors: Partial<Record<keyof T, string>>;
+    /** Fields that have been touched (blurred) */
+    touched: Partial<Record<keyof T, boolean>>;
+    /** Whether the form is currently valid (no errors) */
+    isValid: boolean;
+    /** Whether the form is currently submitting */
+    isSubmitting: boolean;
+    /** Returns a change handler for a specific field */
+    handleChange: (field: keyof T) => (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement>) => void;
+    /** Returns a blur handler for a specific field */
+    handleBlur: (field: keyof T) => () => void;
+    /** Submit handler (validates all fields first) */
+    handleSubmit: (e?: React.FormEvent) => Promise<void>;
+    /** Reset form to initial values */
+    reset: () => void;
+    /** Set a specific field value programmatically */
+    setFieldValue: (field: keyof T, value: unknown) => void;
+    /** Set a specific field error programmatically */
+    setFieldError: (field: keyof T, error: string) => void;
+}
+/**
+ * useAniccaForm — A comprehensive form state management hook with
+ * field-level validation, touch tracking, and async submit support.
+ *
+ * @param config - Form configuration with initial values, validation schema, and submit handler
+ * @returns Form state and handler methods
+ *
+ * @example
+ * ```tsx
+ * const form = useAniccaForm({
+ *   initialValues: { email: '', password: '' },
+ *   validationSchema: {
+ *     email: [required(), email()],
+ *     password: [required(), minLength(8)],
+ *   },
+ *   onSubmit: async (values) => { await login(values) },
+ * })
+ * ```
+ */
+export declare function useAniccaForm<T extends Record<string, unknown>>(config: UseAniccaFormConfig<T>): UseAniccaFormReturn<T>;

package/dist/validation/index.d.ts

@@ -0,0 +1,2 @@
+export * from './rules';
+export * from './hooks/useAniccaForm';

package/dist/validation/rules/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A validation rule consisting of a validate function and error message.
+ */
+export interface ValidationRule {
+    /** Validation function that returns true if valid */
+    validate: (value: unknown) => boolean;
+    /** Error message when validation fails */
+    message: string;
+}
+/**
+ * Creates a required validation rule.
+ * Fails if value is null, undefined, empty string, or empty array.
+ *
+ * @param message - Custom error message
+ * @returns ValidationRule
+ */
+export declare function required(message?: string): ValidationRule;
+/**
+ * Creates an email validation rule.
+ * Fails if value does not match standard email format.
+ *
+ * @param message - Custom error message
+ * @returns ValidationRule
+ */
+export declare function email(message?: string): ValidationRule;
+/**
+ * Creates a minimum length validation rule.
+ *
+ * @param min - Minimum string length
+ * @param message - Custom error message
+ * @returns ValidationRule
+ */
+export declare function minLength(min: number, message?: string): ValidationRule;
+/**
+ * Creates a maximum length validation rule.
+ *
+ * @param max - Maximum string length
+ * @param message - Custom error message
+ * @returns ValidationRule
+ */
+export declare function maxLength(max: number, message?: string): ValidationRule;
+/**
+ * Creates a regex pattern validation rule.
+ *
+ * @param regex - Regular expression to test against
+ * @param message - Custom error message
+ * @returns ValidationRule
+ */
+export declare function pattern(regex: RegExp, message?: string): ValidationRule;
+/**
+ * Creates a minimum value validation rule for numbers.
+ *
+ * @param value - Minimum allowed value
+ * @param message - Custom error message
+ * @returns ValidationRule
+ */
+export declare function min(value: number, message?: string): ValidationRule;
+/**
+ * Creates a maximum value validation rule for numbers.
+ *
+ * @param value - Maximum allowed value
+ * @param message - Custom error message
+ * @returns ValidationRule
+ */
+export declare function max(value: number, message?: string): ValidationRule;
+/**
+ * Creates a custom validation rule with a user-provided function.
+ *
+ * @param fn - Custom validation function
+ * @param message - Error message when validation fails
+ * @returns ValidationRule
+ */
+export declare function custom(fn: (value: unknown) => boolean, message: string): ValidationRule;

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "anicca-ui",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A production-ready React utility library with dashboard components, form validation, date manipulation, and general utilities",
+  "main": "dist/anicca-ui.umd.js",
+  "module": "dist/anicca-ui.es.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/anicca-ui.es.js",
+      "require": "./dist/anicca-ui.umd.js"
+    },
+    "./styles.css": {
+      "default": "./dist/anicca-ui.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "prebuild": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "tsc --noEmit && vite build",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/react-vite": "^8.6.18",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "storybook": "^8.6.18",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.0.0",
+    "vite": "^5.0.0",
+    "vite-plugin-dts": "^3.0.0"
+  },
+  "keywords": [
+    "react",
+    "utility",
+    "dashboard",
+    "validation",
+    "date",
+    "hooks"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}