@flikk/ui 1.0.0-beta.1

package/dist/utils/stateMachine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Form State Machine Logic
+ * Lightweight engine for declarative form transitions and branching.
+ */
+export type StateIdentifier = string;
+export interface StateMachineConfig<TContext = any> {
+    /** The initial state name */
+    initial: StateIdentifier;
+    /** State definitions */
+    states: Record<StateIdentifier, StateDefinition<TContext>>;
+}
+export interface StateDefinition<TContext = any> {
+    /** Map of events to transitions */
+    on?: Record<string, Transition<TContext>>;
+    /** Actions executed when entering this state */
+    entry?: Array<(context: TContext) => void>;
+    /** Actions executed when exiting this state */
+    exit?: Array<(context: TContext) => void>;
+}
+export type Transition<TContext = any> = StateIdentifier | TransitionConfig<TContext>;
+export interface TransitionConfig<TContext = any> {
+    /** Target state */
+    target: StateIdentifier;
+    /** Optional conditional guard */
+    guard?: (context: TContext) => boolean;
+    /** Actions to execute during transition */
+    actions?: Array<(context: TContext) => void>;
+}
+/**
+ * Result of a state transition
+ */
+export interface TransitionResult<TContext> {
+    /** The new state name */
+    value: StateIdentifier;
+    /** Actions to be performed by the runner */
+    actions: Array<(context: TContext) => void>;
+    /** Whether the transition actually occurred */
+    changed: boolean;
+}
+/**
+ * Pure transition function for the state machine
+ */
+export declare function transition<TContext>(config: StateMachineConfig<TContext>, currentState: StateIdentifier, event: string, context: TContext): TransitionResult<TContext>;

package/dist/utils/streamingErrors.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Streaming Error Classes
+ * Defines error types for SSE streaming with retryability flags
+ */
+/**
+ * Base streaming error interface
+ */
+export interface StreamingError {
+    type: 'network' | 'timeout' | 'parse' | 'abort' | 'server';
+    message: string;
+    details?: unknown;
+    retryable: boolean;
+}
+/**
+ * Network error - typically connection issues or fetch failures
+ * Retryable: Yes
+ */
+export declare class StreamingNetworkError extends Error implements StreamingError {
+    details?: unknown | undefined;
+    type: "network";
+    retryable: boolean;
+    constructor(message: string, details?: unknown | undefined);
+}
+/**
+ * Timeout error - request exceeded specified timeout duration
+ * Retryable: Yes
+ */
+export declare class StreamingTimeoutError extends Error implements StreamingError {
+    type: "timeout";
+    retryable: boolean;
+    constructor(timeout: number);
+}
+/**
+ * Parse error - invalid JSON or malformed SSE data
+ * Retryable: No (indicates server-side issue or format mismatch)
+ */
+export declare class StreamingParseError extends Error implements StreamingError {
+    chunk?: string | undefined;
+    type: "parse";
+    retryable: boolean;
+    constructor(message: string, chunk?: string | undefined);
+}
+/**
+ * Abort error - user manually cancelled the stream
+ * Retryable: No (user initiated)
+ */
+export declare class StreamingAbortError extends Error implements StreamingError {
+    type: "abort";
+    retryable: boolean;
+    constructor();
+}
+/**
+ * Server error - HTTP error response from server (4xx, 5xx)
+ * Retryable: No for 4xx, could be Yes for 5xx but defaulting to No
+ */
+export declare class StreamingServerError extends Error implements StreamingError {
+    status: number;
+    details?: unknown | undefined;
+    type: "server";
+    retryable: boolean;
+    constructor(status: number, statusText: string, details?: unknown | undefined);
+}
+/**
+ * Normalize any error into a StreamingError
+ * Used to convert unknown errors (from fetch, network, etc.) into typed streaming errors
+ *
+ * @param error - Any error object
+ * @returns Normalized StreamingError
+ */
+export declare const normalizeError: (error: unknown) => StreamingError;

package/dist/utils/streamingErrors.js

@@ -0,0 +1,93 @@
+/**
+ * Streaming Error Classes
+ * Defines error types for SSE streaming with retryability flags
+ */
+/**
+ * Network error - typically connection issues or fetch failures
+ * Retryable: Yes
+ */
+class StreamingNetworkError extends Error {
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.type = 'network';
+        this.retryable = true;
+        this.name = 'StreamingNetworkError';
+    }
+}
+/**
+ * Timeout error - request exceeded specified timeout duration
+ * Retryable: Yes
+ */
+class StreamingTimeoutError extends Error {
+    constructor(timeout) {
+        super(`Request timeout after ${timeout}ms`);
+        this.type = 'timeout';
+        this.retryable = true;
+        this.name = 'StreamingTimeoutError';
+    }
+}
+/**
+ * Parse error - invalid JSON or malformed SSE data
+ * Retryable: No (indicates server-side issue or format mismatch)
+ */
+class StreamingParseError extends Error {
+    constructor(message, chunk) {
+        super(message);
+        this.chunk = chunk;
+        this.type = 'parse';
+        this.retryable = false;
+        this.name = 'StreamingParseError';
+    }
+}
+/**
+ * Abort error - user manually cancelled the stream
+ * Retryable: No (user initiated)
+ */
+class StreamingAbortError extends Error {
+    constructor() {
+        super('Stream aborted by user');
+        this.type = 'abort';
+        this.retryable = false;
+        this.name = 'StreamingAbortError';
+    }
+}
+/**
+ * Server error - HTTP error response from server (4xx, 5xx)
+ * Retryable: No for 4xx, could be Yes for 5xx but defaulting to No
+ */
+class StreamingServerError extends Error {
+    constructor(status, statusText, details) {
+        super(`Server error: ${status} ${statusText}`);
+        this.status = status;
+        this.details = details;
+        this.type = 'server';
+        this.retryable = false;
+        this.name = 'StreamingServerError';
+    }
+}
+/**
+ * Normalize any error into a StreamingError
+ * Used to convert unknown errors (from fetch, network, etc.) into typed streaming errors
+ *
+ * @param error - Any error object
+ * @returns Normalized StreamingError
+ */
+const normalizeError = (error) => {
+    // Handle AbortController abortion
+    if (error instanceof DOMException && error.name === 'AbortError') {
+        return new StreamingAbortError();
+    }
+    // Already a streaming error - return as-is
+    if (error instanceof StreamingNetworkError ||
+        error instanceof StreamingTimeoutError ||
+        error instanceof StreamingParseError ||
+        error instanceof StreamingServerError ||
+        error instanceof StreamingAbortError) {
+        return error;
+    }
+    // Unknown error - treat as network error (retryable)
+    return new StreamingNetworkError(error instanceof Error ? error.message : 'Unknown streaming error', error);
+};
+
+export { StreamingAbortError, StreamingNetworkError, StreamingParseError, StreamingServerError, StreamingTimeoutError, normalizeError };

package/dist/utils/typeaheadUtils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Typeahead utilities for dropdown components
+ * Provides functions to search and navigate through options by typing
+ */
+export interface TypeaheadOption {
+    /** Display label for the option */
+    label: string;
+    /** Whether the option is disabled */
+    disabled?: boolean;
+}
+export interface FindNextMatchingOptionParams<T extends TypeaheadOption> {
+    /** Array of options to search through */
+    options: T[];
+    /** The character or string to search for */
+    searchChar: string;
+    /** Current highlighted index (to start searching from next item) */
+    currentIndex: number;
+    /** Previous search string (for multi-character matching) */
+    previousSearch?: string;
+}
+/**
+ * Finds the next matching option based on typeahead input
+ * Supports cycling through multiple matches and multi-character search
+ */
+export declare function findNextMatchingOption<T extends TypeaheadOption>({ options, searchChar, currentIndex, previousSearch, }: FindNextMatchingOptionParams<T>): number;
+/**
+ * Checks if a character is valid for typeahead search
+ * Excludes control keys and special navigation keys
+ */
+export declare function isValidTypeaheadChar(key: string): boolean;
+/**
+ * Debounce timeout for resetting typeahead search
+ * After this timeout, the next character starts a new search
+ */
+export declare const TYPEAHEAD_TIMEOUT_MS = 1000;

package/dist/utils/typeaheadUtils.js

@@ -0,0 +1,60 @@
+/**
+ * Typeahead utilities for dropdown components
+ * Provides functions to search and navigate through options by typing
+ */
+/**
+ * Finds the next matching option based on typeahead input
+ * Supports cycling through multiple matches and multi-character search
+ */
+function findNextMatchingOption({ options, searchChar, currentIndex, previousSearch = '', }) {
+    if (!searchChar || options.length === 0) {
+        return -1;
+    }
+    // Build the search string (either new character or continuation)
+    const searchString = searchChar.toLowerCase();
+    const isNewSearch = previousSearch === '' || !searchString.startsWith(previousSearch.toLowerCase());
+    // For single character searches, we want to cycle through matches
+    // For multi-character, we want to find the best match
+    const searchTerm = isNewSearch ? searchString : searchString;
+    // Find all matching options (not disabled)
+    const matchingIndices = [];
+    options.forEach((option, index) => {
+        if (!option.disabled && option.label.toLowerCase().startsWith(searchTerm)) {
+            matchingIndices.push(index);
+        }
+    });
+    if (matchingIndices.length === 0) {
+        return -1;
+    }
+    // If it's a single character and we're repeating the same character,
+    // cycle to the next match after current position
+    if (searchString.length === 1 && searchString === previousSearch.toLowerCase()) {
+        const currentMatchIndex = matchingIndices.findIndex(index => index > currentIndex);
+        return currentMatchIndex >= 0
+            ? matchingIndices[currentMatchIndex]
+            : matchingIndices[0]; // Wrap to first match
+    }
+    // For new searches or multi-character, find the first match after current position
+    // or wrap to the first match if none found after current
+    const nextMatch = matchingIndices.find(index => index > currentIndex);
+    return nextMatch !== undefined ? nextMatch : matchingIndices[0];
+}
+const TYPEAHEAD_CHAR_REGEX = /[a-zA-Z0-9\s]/;
+/**
+ * Checks if a character is valid for typeahead search
+ * Excludes control keys and special navigation keys
+ */
+function isValidTypeaheadChar(key) {
+    // Allow letters, numbers, and some symbols
+    if (key.length === 1) {
+        return TYPEAHEAD_CHAR_REGEX.test(key);
+    }
+    return false;
+}
+/**
+ * Debounce timeout for resetting typeahead search
+ * After this timeout, the next character starts a new search
+ */
+const TYPEAHEAD_TIMEOUT_MS = 1000;
+
+export { TYPEAHEAD_TIMEOUT_MS, findNextMatchingOption, isValidTypeaheadChar };

package/dist/utils/useClickOutside.d.ts

@@ -0,0 +1 @@
+export { useClickOutside } from '../hooks/useClickOutside';

package/package.json

@@ -0,0 +1,168 @@
+{
+  "name": "@flikk/ui",
+  "version": "1.0.0-beta.1",
+  "description": "A modern React component library built with TypeScript, Tailwind CSS v4, and Framer Motion. Follows the shadcn philosophy with complete className override support.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": [
+    "*.css",
+    "*.scss",
+    "./dist/styles.css",
+    "./src/global.scss"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./core": {
+      "import": "./dist/components/core/index.js",
+      "types": "./dist/components/core/index.d.ts"
+    },
+    "./forms": {
+      "import": "./dist/components/forms/index.js",
+      "types": "./dist/components/forms/index.d.ts"
+    },
+    "./charts": {
+      "import": "./dist/components/charts/index.js",
+      "types": "./dist/components/charts/index.d.ts"
+    },
+    "./effects": {
+      "import": "./dist/components/effects/index.js",
+      "types": "./dist/components/effects/index.d.ts"
+    },
+    "./ai": {
+      "import": "./dist/components/ai/index.js",
+      "types": "./dist/components/ai/index.d.ts"
+    },
+    "./components/*": {
+      "import": "./dist/components/*.js",
+      "types": "./dist/components/*.d.ts"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./tailwind.preset.cjs": "./tailwind.preset.cjs",
+    "./shadcn-compat.css": "./src/shadcn-compat.css"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "tailwind.preset.cjs",
+    "src/shadcn-compat.css"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "rollup -c && npm run build:css",
+    "build:css": "tailwindcss -m -i ./src/tailwind-config.css -o ./dist/styles.css",
+    "watch": "rollup -c -w",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "clean": "rimraf dist",
+    "storybook": "concurrently \"npm run watch:css:dev\" \"storybook dev -p 6006\"",
+    "watch:css:dev": "tailwindcss --watch -i ./src/tailwind-config.css -o ./src/index.css",
+    "build:css:dev": "tailwindcss -i ./src/tailwind-config.css -o ./src/index.css",
+    "storybook:clean": "rm -rf storybook-static node_modules/.cache",
+    "storybook:fresh": "npm run storybook:clean && npm run storybook",
+    "build-storybook": "npm run build-storybook:css && storybook build",
+    "build-storybook:css": "tailwindcss -m -i ./src/tailwind-config.css -o ./src/index.css"
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "components",
+    "ui",
+    "tailwindcss",
+    "framer-motion",
+    "component-library",
+    "shadcn",
+    "design-system"
+  ],
+  "author": "Espranza Innovations <g.singh@espranza.net>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.19.0",
+    "npm": ">=10.0.0"
+  },
+  "peerDependencies": {
+    "@heroicons/react": "^2.2.0",
+    "@react-three/drei": ">=10.0.0",
+    "@react-three/fiber": ">=9.0.0",
+    "clsx": "^2.1.1",
+    "motion": "^12.19.1",
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "react-markdown": "^9.0.1 || ^10.0.0",
+    "react-syntax-highlighter": "^15.5.0 || ^16.0.0",
+    "remark-gfm": "^4.0.0",
+    "tailwind-merge": "^3.0.2",
+    "tailwindcss": "^4.0.9",
+    "three": ">=0.170.0"
+  },
+  "peerDependenciesMeta": {
+    "react-markdown": {
+      "optional": true
+    },
+    "react-syntax-highlighter": {
+      "optional": true
+    },
+    "remark-gfm": {
+      "optional": true
+    },
+    "three": {
+      "optional": true
+    },
+    "@react-three/fiber": {
+      "optional": true
+    },
+    "@react-three/drei": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^5.0.0",
+    "@emotion/is-prop-valid": "^1.4.0",
+    "@heroicons/react": "^2.2.0",
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.5.0",
+    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
+    "@storybook/addon-a11y": "^10.2.3",
+    "@storybook/addon-docs": "^10.2.3",
+    "@storybook/addon-links": "^10.2.3",
+    "@storybook/addon-mcp": "^0.2.2",
+    "@storybook/addon-onboarding": "^10.2.3",
+    "@storybook/addon-themes": "^10.2.3",
+    "@storybook/addon-webpack5-compiler-swc": "^4.0.2",
+    "@storybook/react-webpack5": "^10.2.3",
+    "@tailwindcss/cli": "^4.1.18",
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3",
+    "@types/react-syntax-highlighter": "^15.5.11",
+    "@types/three": "^0.182.0",
+    "autoprefixer": "^10.4.24",
+    "clsx": "^2.1.1",
+    "concurrently": "^9.2.1",
+    "eslint-plugin-storybook": "^10.2.7",
+    "motion": "^12.33.0",
+    "postcss": "^8.5.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-markdown": "^10.1.0",
+    "react-syntax-highlighter": "^16.1.0",
+    "remark-gfm": "^4.0.1",
+    "rollup": "^4.57.1",
+    "storybook": "^10.2.3",
+    "tailwind-merge": "^3.4.0",
+    "three": "^0.182.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "gsap": "^3.14.2"
+  }
+}

package/tailwind.preset.cjs

@@ -0,0 +1,102 @@
+/**
+ * Flikkui Tailwind Preset
+ * Usage (Tailwind v3/v4 config file):
+ *   module.exports = { presets: [require('flikkui/tailwind.preset.cjs')] }
+ * This maps Flikkui CSS variables to Tailwind color tokens like bg-primary.
+ */
+
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        primary: {
+          50: 'var(--color-primary-50)',
+          100: 'var(--color-primary-100)',
+          200: 'var(--color-primary-200)',
+          300: 'var(--color-primary-300)',
+          400: 'var(--color-primary-400)',
+          500: 'var(--color-primary-500)',
+          600: 'var(--color-primary-600)',
+          700: 'var(--color-primary-700)',
+          800: 'var(--color-primary-800)',
+          900: 'var(--color-primary-900)',
+          950: 'var(--color-primary-950)',
+          DEFAULT: 'var(--color-primary-600)'
+        },
+        danger: {
+          50: 'var(--color-danger-50)',
+          100: 'var(--color-danger-100)',
+          200: 'var(--color-danger-200)',
+          300: 'var(--color-danger-300)',
+          400: 'var(--color-danger-400)',
+          500: 'var(--color-danger-500)',
+          600: 'var(--color-danger-600)',
+          700: 'var(--color-danger-700)',
+          800: 'var(--color-danger-800)',
+          900: 'var(--color-danger-900)',
+          950: 'var(--color-danger-950)',
+          DEFAULT: 'var(--color-danger-600)'
+        },
+        success: {
+          50: 'var(--color-success-50)',
+          100: 'var(--color-success-100)',
+          200: 'var(--color-success-200)',
+          300: 'var(--color-success-300)',
+          400: 'var(--color-success-400)',
+          500: 'var(--color-success-500)',
+          600: 'var(--color-success-600)',
+          700: 'var(--color-success-700)',
+          800: 'var(--color-success-800)',
+          900: 'var(--color-success-900)',
+          950: 'var(--color-success-950)',
+          DEFAULT: 'var(--color-success-500)'
+        },
+        warning: {
+          50: 'var(--color-warning-50)',
+          100: 'var(--color-warning-100)',
+          200: 'var(--color-warning-200)',
+          300: 'var(--color-warning-300)',
+          400: 'var(--color-warning-400)',
+          500: 'var(--color-warning-500)',
+          600: 'var(--color-warning-600)',
+          700: 'var(--color-warning-700)',
+          800: 'var(--color-warning-800)',
+          900: 'var(--color-warning-900)',
+          950: 'var(--color-warning-950)',
+          DEFAULT: 'var(--color-warning-600)'
+        },
+        text: {
+          primary: 'var(--color-text-primary)',
+          secondary: 'var(--color-text-secondary)',
+          muted: 'var(--color-text-muted)',
+          placeholder: 'var(--color-text-placeholder)',
+          disabled: 'var(--color-text-disabled)',
+          inverse: 'var(--color-text-inverse)'
+        },
+        background: {
+          DEFAULT: 'var(--color-background)',
+          secondary: 'var(--color-background-secondary)',
+          tertiary: 'var(--color-background-tertiary)',
+          quaternary: 'var(--color-background-quaternary)',
+          quinary: 'var(--color-background-quinary)'
+        },
+        border: 'var(--color-border)'
+      },
+      fontFamily: {
+        sans: ['var(--font-family-base)', 'sans-serif']
+      },
+      fontWeight: {
+        light: 'var(--font-weight-light)',
+        normal: 'var(--font-weight-normal)',
+        medium: 'var(--font-weight-medium)',
+        semibold: 'var(--font-weight-semibold)',
+        bold: 'var(--font-weight-bold)',
+        extrabold: 'var(--font-weight-extrabold)'
+      },
+      borderRadius: {
+        form: 'var(--form-rounded)',
+        button: 'var(--button-rounded)'
+      }
+    }
+  }
+};