@zvoove/unity-ui 2.30.0 → 2.32.1

package/dist/src/components/Uploader/types/file.d.ts

@@ -0,0 +1,116 @@
+import { default as React } from 'react';
+import { FILE_ERROR } from './errors';
+/**
+ * Source from which a file was added to the uploader.
+ */
+export type FileSource = 'picker' | 'drop';
+/**
+ * Status of a file in the upload process.
+ */
+export declare enum FILE_STATUS {
+    /** File is added but upload has not started. */
+    IDLE = "idle",
+    /** File is queued and waiting for upload. */
+    PENDING = "pending",
+    /** File upload is in progress. */
+    UPLOADING = "uploading",
+    /** File upload was canceled by user. */
+    CANCELED = "canceled",
+    /** File upload failed. */
+    FAILED = "failed",
+    /** File upload completed successfully. */
+    SUCCESS = "success"
+}
+/**
+ * Additional information that can be attached to a file.
+ */
+export interface FileInfo {
+    /**
+     * Additional text to display below the file name.
+     * @example "PDF Document"
+     */
+    additionalInfo?: string;
+    /**
+     * Custom React node to render as the file label.
+     * When provided, replaces the default file name display.
+     */
+    customLabel?: React.ReactNode;
+    /**
+     * Allow additional custom properties.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Current state of a file in the uploader.
+ */
+export interface FileState {
+    /**
+     * Current status of the file.
+     */
+    status: FILE_STATUS;
+    /**
+     * Whether the file has a validation or upload error.
+     */
+    hasError: boolean;
+    /**
+     * The error type if the file has an error.
+     */
+    error?: FILE_ERROR;
+    /**
+     * Human-readable error message.
+     */
+    errorMessage?: string;
+    /**
+     * Upload progress percentage (0-100).
+     * Only relevant when status is UPLOADING.
+     */
+    progress?: number;
+    /**
+     * Custom status message to display.
+     * Overrides the default status text when provided.
+     */
+    statusMessage?: string;
+}
+/**
+ * Represents a file in the uploader with its metadata and state.
+ */
+export interface FileItem {
+    /**
+     * Unique identifier for this file item.
+     */
+    id: string;
+    /**
+     * The actual File object.
+     */
+    file: File;
+    /**
+     * Additional information about the file.
+     */
+    info: FileInfo;
+    /**
+     * Current state of the file.
+     */
+    state: FileState;
+    /**
+     * How the file was added to the uploader.
+     */
+    source: FileSource;
+}
+/**
+ * Represents a file that was rejected during validation.
+ * These files are not added to the file list but shown in the rejection list.
+ */
+export interface RejectedFile {
+    /**
+     * The actual File object that was rejected.
+     */
+    file: File;
+    /**
+     * The validation error that caused the rejection.
+     */
+    error: FILE_ERROR;
+    /**
+     * Human-readable error message.
+     */
+    errorMessage: string;
+}

package/dist/src/components/Uploader/types/index.d.ts

@@ -0,0 +1,3 @@
+export * from './errors';
+export * from './file';
+export * from './events';

package/dist/src/components/Uploader/utils/createFetchUpload.d.ts

@@ -0,0 +1,32 @@
+import { UploadFunction } from '../hooks/useFileUpload';
+interface FetchUploadOptions {
+    /**
+     * The URL to upload the file to.
+     */
+    url: string;
+    /**
+     * HTTP method to use for the upload.
+     * @default 'POST'
+     */
+    method?: string;
+    /**
+     * HTTP headers to include in the request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * The key to use when appending the file to FormData.
+     * @default 'file'
+     */
+    formDataKey?: string;
+    /**
+     * Additional data to include in the FormData.
+     */
+    additionalData?: Record<string, string | Blob>;
+    /**
+     * Request timeout in milliseconds.
+     * @default 0 (no timeout)
+     */
+    timeout?: number;
+}
+export declare function createFetchUpload(options: FetchUploadOptions): UploadFunction;
+export {};

package/dist/src/components/Uploader/utils/createXhrUpload.d.ts

@@ -0,0 +1,45 @@
+import { UploadFunction } from '../hooks/useFileUpload';
+interface XhrUploadOptions {
+    /**
+     * The URL to upload the file to.
+     */
+    url: string;
+    /**
+     * HTTP method to use for the upload.
+     * @default 'POST'
+     */
+    method?: string;
+    /**
+     * HTTP headers to include in the request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * The key to use when appending the file to FormData.
+     * @default 'file'
+     */
+    formDataKey?: string;
+    /**
+     * Additional data to include in the FormData.
+     */
+    additionalData?: Record<string, string | Blob>;
+}
+/**
+ * Creates an XHR-based upload function for use with useFileUpload.
+ * Provides progress tracking and cancellation support.
+ *
+ * @param options - Configuration options for the XHR upload
+ * @returns An upload function compatible with useFileUpload
+ *
+ * @example
+ * ```tsx
+ * const { uploadFile } = useFileUpload({
+ *   uploaderRef,
+ *   uploadFunction: createXhrUpload({
+ *     url: 'https://api.example.com/upload',
+ *     headers: { 'Authorization': 'Bearer token' }
+ *   })
+ * });
+ * ```
+ */
+export declare function createXhrUpload(options: XhrUploadOptions): UploadFunction;
+export {};

package/dist/src/components/Uploader/utils/detectDuplicates.d.ts

@@ -0,0 +1,5 @@
+export declare const getFileIdentityKey: (file: File) => string;
+export declare const detectDuplicates: (files: File[]) => Map<number, {
+    file: File;
+    duplicateOf: number;
+}>;

package/dist/src/components/Uploader/utils/formatFileSize.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_FILE_SIZE_UNITS: readonly ["Bytes", "KB", "MB", "GB"];
+export type FileSizeUnits = readonly [string, string, string, string];
+export declare const formatFileSize: (bytes: number, units?: FileSizeUnits) => string;

package/dist/src/components/Uploader/utils/generateId.d.ts

@@ -0,0 +1 @@
+export declare const generateId: () => string;

package/dist/src/components/Uploader/utils/getFileExtension.d.ts

@@ -0,0 +1 @@
+export declare const getFileExtension: (file: File | string) => string;

package/dist/src/components/Uploader/utils/index.d.ts

@@ -0,0 +1,8 @@
+export { formatFileSize, DEFAULT_FILE_SIZE_UNITS } from './formatFileSize';
+export { generateId } from './generateId';
+export { detectDuplicates, getFileIdentityKey } from './detectDuplicates';
+export { validateFileType } from './validateFileType';
+export { getFileExtension } from './getFileExtension';
+export { normalizeFile, normalizeFileWithError } from './normalizeFile';
+export { createXhrUpload } from './createXhrUpload';
+export { createFetchUpload } from './createFetchUpload';

package/dist/src/components/Uploader/utils/normalizeFile.d.ts

@@ -0,0 +1,3 @@
+import { FILE_ERROR, FileItem, FileSource } from '../types';
+export declare const normalizeFile: (file: File, source: FileSource) => FileItem;
+export declare const normalizeFileWithError: (file: File, source: FileSource, error: FILE_ERROR, errorMessage: string) => FileItem;

package/dist/src/components/Uploader/utils/validateFileType.d.ts

@@ -0,0 +1 @@
+export declare const validateFileType: (file: File, accept?: string) => boolean;

package/dist/src/components/UserArea/UserArea.d.ts

@@ -0,0 +1,3 @@
+import { UserAreaProps } from './UserArea.types';
+declare const UserArea: import('react').ForwardRefExoticComponent<UserAreaProps & import('react').RefAttributes<HTMLDivElement>>;
+export default UserArea;

package/dist/src/components/UserArea/UserArea.styled.d.ts

@@ -0,0 +1,65 @@
+export declare const userAreaStyles: import('tailwind-variants').TVReturnType<{
+    clickable: {
+        true: string[];
+    };
+    compact: {
+        true: string[];
+        false: never[];
+    };
+    showInfo: {
+        true: string[];
+        false: string[];
+    };
+    infoPosition: {
+        left: string[];
+        right: never[];
+    };
+}, undefined, string[], {
+    clickable: {
+        true: string[];
+    };
+    compact: {
+        true: string[];
+        false: never[];
+    };
+    showInfo: {
+        true: string[];
+        false: string[];
+    };
+    infoPosition: {
+        left: string[];
+        right: never[];
+    };
+}, undefined, import('tailwind-variants').TVReturnType<{
+    clickable: {
+        true: string[];
+    };
+    compact: {
+        true: string[];
+        false: never[];
+    };
+    showInfo: {
+        true: string[];
+        false: string[];
+    };
+    infoPosition: {
+        left: string[];
+        right: never[];
+    };
+}, undefined, string[], unknown, unknown, undefined>>;
+export declare const userInfoStyles: import('tailwind-variants').TVReturnType<{
+    visible: {
+        true: string[];
+        false: string[];
+    };
+}, undefined, string[], {
+    visible: {
+        true: string[];
+        false: string[];
+    };
+}, undefined, import('tailwind-variants').TVReturnType<{
+    visible: {
+        true: string[];
+        false: string[];
+    };
+}, undefined, string[], unknown, unknown, undefined>>;

package/dist/src/components/UserArea/UserArea.types.d.ts

@@ -0,0 +1,49 @@
+import { AvatarProps, PopUpMenuItem, PopUpMenuPlacement } from '../../index.ts';
+import { ResponsiveType } from '../../types';
+export interface UserAreaProps {
+    /**
+     * The user's display name
+     */
+    name: string;
+    /**
+     * Optional subtitle (e.g. role, company)
+     */
+    subtitle?: string;
+    /**
+     * The avatar of the user (see AvatarProps)
+     */
+    avatar: AvatarProps;
+    /**
+     * Whether to display in compact mode (small avatar)
+     * @default false
+     */
+    compact?: boolean;
+    /**
+     * Whether to show the user info text (name and subtitle)
+     * @default true
+     */
+    showInfo?: boolean;
+    /**
+     * Position of the info text relative to the avatar
+     * @default 'right'
+     */
+    infoPosition?: 'left' | 'right';
+    /**
+     * Menu items displayed in a PopUpMenu when the user area is clicked
+     */
+    menuItems?: PopUpMenuItem[];
+    /**
+     * Callback when a menu item is clicked
+     */
+    onItemClick?: (item: PopUpMenuItem) => void;
+    /**
+     * The max height of the popup menu
+     * @default '80dvh'
+     */
+    menuMaxHeight?: ResponsiveType<number | string>;
+    /**
+     * The placement of the popup menu
+     * @default 'top-left'
+     */
+    menuPlacement?: ResponsiveType<PopUpMenuPlacement>;
+}

package/dist/src/components/UserArea/index.d.ts

@@ -0,0 +1,2 @@
+export { default as UserArea } from './UserArea';
+export type { UserAreaProps } from './UserArea.types';

package/dist/src/components/ZvooveBrand/ZvooveBrand.constants.d.ts

@@ -0,0 +1,26 @@
+import { ZvooveBrandSize, ZvooveProduct } from './ZvooveBrand.types';
+type ProductIconComponent = (props: {
+    size?: number;
+    color?: string;
+}) => React.JSX.Element;
+interface ProductDescriptor {
+    Icon: ProductIconComponent;
+    /** Tagline shown next to the word mark. `null` means the product has no tagline. */
+    tagline: string | null;
+}
+export declare const productMap: Record<ZvooveProduct, ProductDescriptor>;
+interface BrandSize {
+    /** Logomark size in pixels (square). */
+    icon: number;
+    /** Visible "zvoove" wordmark glyph height in pixels. */
+    name: number;
+    /** Tagline font size in pixels. */
+    tagline: number;
+}
+/**
+ * Size scale for the brand lock-up. `md` matches the Figma baseline
+ * (icon 32px, wordmark 13px, tagline 24px). All other sizes scale
+ * proportionally so the design ratios stay intact.
+ */
+export declare const sizeMap: Record<ZvooveBrandSize, BrandSize>;
+export {};

package/dist/src/components/ZvooveBrand/ZvooveBrand.d.ts

@@ -0,0 +1,6 @@
+import { ZvooveBrandProps } from './ZvooveBrand.types';
+declare const ZvooveBrand: {
+    ({ product, iconStyle, size, hideIcon, hideName, hideTagline, tagline: taglineProp, iconSize: iconSizeProp, nameHeight: nameHeightProp, taglineSize: taglineSizeProp, }: ZvooveBrandProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export default ZvooveBrand;

package/dist/src/components/ZvooveBrand/ZvooveBrand.types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * The zvoove product whose brand identity to display.
+ * Determines the logomark and the tagline text (e.g. "One", "Recruit").
+ */
+export type ZvooveProduct = 'default' | 'one' | 'recruit' | 'invoice-monitor' | 'go' | 'insights' | 'work-expert' | 'elevate' | 'cashlink' | 'docs-ai';
+/**
+ * Visual style of the logomark.
+ * - `duotone`: brand colors in light mode, switches to the themed flat
+ *   variant in dark mode so the logomark always follows the surface tone.
+ * - `flat`: a single-color version using the surface foreground token,
+ *   themed in both light and dark mode.
+ */
+export type ZvooveBrandIconStyle = 'duotone' | 'flat';
+/**
+ * Overall size of the brand lock-up. Each tier scales the logomark,
+ * wordmark and tagline together while keeping the design ratios.
+ * `md` matches the Figma baseline (icon 32px, wordmark 13px, tagline 24px).
+ */
+export type ZvooveBrandSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+export interface ZvooveBrandProps {
+    /**
+     * The zvoove product to display. Drives both the logomark and the tagline.
+     * @default 'default'
+     */
+    product?: ZvooveProduct;
+    /**
+     * Visual style of the logomark.
+     * @default 'duotone'
+     */
+    iconStyle?: ZvooveBrandIconStyle;
+    /**
+     * Overall size of the brand lock-up. Sets sensible defaults for the
+     * logomark, wordmark and tagline while keeping the Figma design ratios.
+     * Individual `iconSize`, `nameHeight` and `taglineSize` props can
+     * override the values picked from the size.
+     * @default 'md'
+     */
+    size?: ZvooveBrandSize;
+    /**
+     * Hide the logomark.
+     * @default false
+     */
+    hideIcon?: boolean;
+    /**
+     * Hide the "zvoove" wordmark.
+     * @default false
+     */
+    hideName?: boolean;
+    /**
+     * Hide the product tagline (e.g. "One", "Recruit").
+     * Has no effect when `product="default"` since the default brand has no tagline.
+     * @default false
+     */
+    hideTagline?: boolean;
+    /**
+     * Override the product tagline with a custom string. Falls back to the
+     * tagline derived from `product` when omitted. Useful for sub-products,
+     * environment labels (e.g. "Beta", "Staging") or fully custom branding.
+     * Has no effect when `hideTagline` is `true`.
+     */
+    tagline?: string;
+    /**
+     * Override the logomark size in pixels. Falls back to the value derived
+     * from `size`.
+     */
+    iconSize?: number;
+    /**
+     * Override the "zvoove" wordmark height in pixels. Falls back to the
+     * value derived from `size`.
+     */
+    nameHeight?: number;
+    /**
+     * Override the product tagline font size in pixels. Falls back to the
+     * value derived from `size`.
+     */
+    taglineSize?: number;
+}

package/dist/src/components/ZvooveBrand/index.d.ts

@@ -0,0 +1,2 @@
+export { default as ZvooveBrand } from './ZvooveBrand';
+export * from './ZvooveBrand.types';

package/dist/src/config.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Unity UI CLI configuration type.
+ */
+export interface UnityUIConfig {
+    /** Component scaffolding settings */
+    components?: {
+        /** Directory where components are created (default: 'src/components') */
+        directory?: string;
+        /** Barrel file to update with exports (default: 'src/index.ts') */
+        indexFile?: string;
+    };
+    /** AI agent integration settings */
+    ai?: {
+        /** Agent Skills generation settings */
+        skills?: {
+            /** Base directory (or directories) for skills output (default: '.claude') */
+            output?: string | string[];
+        };
+        /** AI rules file generation settings */
+        rules?: {
+            /** Directory where rule files are written (default: '.') */
+            output?: string;
+            /** Output filename (default: 'UNITYUI.md') */
+            filename?: string;
+        };
+    };
+}
+/**
+ * Identity function that provides type hints for unity-ui.config.mjs.
+ *
+ * @example
+ * ```js
+ * // unity-ui.config.mjs
+ * import { defineConfig } from '@zvoove/unity-ui/config';
+ *
+ * export default defineConfig({
+ *   components: {
+ *     directory: 'src/components',
+ *     indexFile: 'src/index.ts',
+ *   },
+ *   ai: {
+ *     skills: { output: '.claude' },
+ *     rules: { output: '.' },
+ *   },
+ * });
+ * ```
+ */
+export declare function defineConfig(config: UnityUIConfig): UnityUIConfig;

package/dist/src/constants/align.d.ts

@@ -0,0 +1,3 @@
+import { AlignItems, FlexResponsiveStyles } from '../types';
+export declare const align: Record<AlignItems, string>;
+export declare const alignResponsiveStyles: FlexResponsiveStyles<'align', AlignItems>;

package/dist/src/constants/breakpoints.d.ts

@@ -0,0 +1,12 @@
+import { Viewport } from '../types';
+export declare const BREAKPOINTS: {
+    readonly minimum: 0;
+    readonly mobile: 768;
+    readonly tablet: 1024;
+    readonly laptop: 1280;
+    readonly desktop: 1536;
+    readonly wide: 1920;
+    readonly ultrawide: 2560;
+};
+/** Ordered array of breakpoints from smallest to largest */
+export declare const BREAKPOINT_ORDER: Viewport[];

package/dist/src/constants/colors.d.ts

@@ -0,0 +1,7 @@
+import { BackgroundColors, ForegroundColors } from '../types';
+export declare const backgroundColors: Record<BackgroundColors, string[]>;
+export declare const backgroundHoverColors: Record<BackgroundColors, string[]>;
+export declare const semanticForegroundColors: Record<BackgroundColors, string[]>;
+export declare const semanticBackgroundColors: Record<ForegroundColors, string[]>;
+export declare const strokeColors: Record<BackgroundColors, string[]>;
+export declare const foregroundColors: Record<ForegroundColors, string[]>;

package/dist/src/constants/direction.d.ts

@@ -0,0 +1,3 @@
+import { FlexDirection, FlexResponsiveStyles } from '../types';
+export declare const direction: Record<FlexDirection, string>;
+export declare const directionResponsiveStyles: FlexResponsiveStyles<'direction', FlexDirection>;

package/dist/src/constants/dom.d.ts

@@ -0,0 +1,5 @@
+/**
+ * CSS selector for all focusable elements in the DOM.
+ * Includes buttons, links, inputs, selects, textareas, and elements with tabindex >= 0
+ */
+export declare const FOCUSABLE_ELEMENTS_SELECTOR = "button, [href], input, select, textarea, [tabindex]:not([tabindex=\"-1\"])";

package/dist/src/constants/gap.d.ts

@@ -0,0 +1,8 @@
+import { GapResponsiveStyles, ResponsiveTypeFixed, SpacingKeys } from '../types';
+export declare const gap: Record<SpacingKeys, string>;
+export declare const responsiveGap: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const gapRow: Record<SpacingKeys, string>;
+export declare const responsiveGapRow: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const gapColumn: Record<SpacingKeys, string>;
+export declare const responsiveGapColumn: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const gapResponsiveStyles: GapResponsiveStyles<'gap'>;

package/dist/src/constants/index.d.ts

@@ -0,0 +1,11 @@
+export * from './breakpoints';
+export * from './colors';
+export * from './padding';
+export * from './margin';
+export * from './gap';
+export * from './dom';
+export * from './justify';
+export * from './align';
+export * from './wrap';
+export * from './direction';
+export * from './overflow';

package/dist/src/constants/justify.d.ts

@@ -0,0 +1,3 @@
+import { FlexResponsiveStyles, JustifyContent } from '../types';
+export declare const justify: Record<JustifyContent, string>;
+export declare const justifyResponsiveStyles: FlexResponsiveStyles<'justify', JustifyContent>;

package/dist/src/constants/margin.d.ts

@@ -0,0 +1,16 @@
+import { ResponsiveStyles, ResponsiveTypeFixed, SpacingKeys } from '../types';
+export declare const margin: Record<SpacingKeys, string>;
+export declare const marginResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const marginX: Record<SpacingKeys, string>;
+export declare const marginXResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const marginY: Record<SpacingKeys, string>;
+export declare const marginYResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const marginTop: Record<SpacingKeys, string>;
+export declare const marginTopResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const marginBottom: Record<SpacingKeys, string>;
+export declare const marginBottomResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const marginLeft: Record<SpacingKeys, string>;
+export declare const marginLeftResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const marginRight: Record<SpacingKeys, string>;
+export declare const marginRightResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const marginResponsiveStyles: ResponsiveStyles<'margin'>;

package/dist/src/constants/overflow.d.ts

@@ -0,0 +1,5 @@
+import { OverflowBase, OverflowYOrX, ResponsiveGenericStyles } from '../types';
+export declare const overflow: Record<OverflowBase, string>;
+export declare const overflowY: Record<OverflowYOrX, string>;
+export declare const overflowX: Record<OverflowYOrX, string>;
+export declare const overflowResponsiveStyles: ResponsiveGenericStyles<'overflow', OverflowBase> & ResponsiveGenericStyles<'overflowY', OverflowYOrX> & ResponsiveGenericStyles<'overflowX', OverflowYOrX>;

package/dist/src/constants/padding.d.ts

@@ -0,0 +1,16 @@
+import { ResponsiveStyles, ResponsiveTypeFixed, SpacingKeys } from '../types';
+export declare const padding: Record<SpacingKeys, string>;
+export declare const paddingResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const paddingX: Record<SpacingKeys, string>;
+export declare const paddingXResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const paddingY: Record<SpacingKeys, string>;
+export declare const paddingYResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const paddingTop: Record<SpacingKeys, string>;
+export declare const paddingTopResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const paddingBottom: Record<SpacingKeys, string>;
+export declare const paddingBottomResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const paddingLeft: Record<SpacingKeys, string>;
+export declare const paddingLeftResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const paddingRight: Record<SpacingKeys, string>;
+export declare const paddingRightResponsive: ResponsiveTypeFixed<Record<SpacingKeys, string>>;
+export declare const paddingResponsiveStyles: ResponsiveStyles<'padding'>;

package/dist/src/constants/wrap.d.ts

@@ -0,0 +1,3 @@
+import { FlexResponsiveStyles, FlexWrap } from '../types';
+export declare const wrap: Record<FlexWrap, string>;
+export declare const wrapResponsiveStyles: FlexResponsiveStyles<'wrap', FlexWrap>;

package/dist/src/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useClickOutside';
+export * from './useBreakpoint';