@1money/component-ui 0.0.23 → 0.0.25

package/AGENTS.md

@@ -1,546 +0,0 @@
-# AGENTS.md
-
-This file provides guidance to Code Agent when working with code in this repository.
-
-## Development Commands
-
-### Development Server
-- `pnpm dev` - Start Storybook development server on port 6205
-- `pnpm start` - Alternative command to start development server
-
-### Building
-- `pnpm build` - Build the component library (both CommonJS and ES modules)
-
-> Note: `omni build -n` (bypass pre-checks) and `omni build --demo` (build Storybook) are omni-door CLI options, not separate pnpm scripts.
-
-### Testing and Linting
-- `pnpm test` - Run Jest tests (passes with no tests by default)
-- `pnpm lint` - Run all linting (ESLint, Prettier, Stylelint)
-- `pnpm lint:fix` - Auto-fix all linting issues
-- `pnpm lint:es` / `pnpm lint:es_fix` - ESLint only
-- `pnpm lint:prettier` / `pnpm lint:prettier_fix` - Prettier only
-- `pnpm lint:style` / `pnpm lint:style_fix` - Stylelint only
-
-### Component Generation (omni-door CLI)
-- `omni new` - Interactive component scaffolding
-- `omni new ComponentName -f` - Generate functional component with given name
-
-> Note: These are omni-door CLI commands, not pnpm scripts. Ensure `@omni-door/cli` is installed globally or use `npx omni-door`.
-
-### Package Management
-- `pnpm release` - Release new version (auto-builds first)
-
-> Note: Release options (`-i` ignore version iteration, `-m 0.3.25` specific version, `-n` bypass pre-checks) are omni-door CLI flags passed through `omni release`.
-
-## Project Architecture
-
-### Component Library Structure
-This is a standalone React component library built with PrimeReact as the base, using the omni-door CLI framework for scaffolding and build processes. Hooks are imported from `@1money/hooks`.
-
-**Core Dependencies:**
-- **@1money/hooks**: Shared React hooks library (linked locally via `file:../1money-hooks`)
-- **PrimeReact**: Base UI component library (>=10.9.0)
-- **react-tooltip**: Tooltip rendering (^5.28.1)
-- **React**: >=16.8.0 with React 19+ for development
-- **TypeScript**: Full TypeScript support with strict mode
-
-**Styling System:**
-- Custom SCSS-based design system (`src/styles/`) with token scales, theme engine, `om-sx` mixin, and atomic utility classes
-- NOT using TailwindCSS — all styling is handled by the internal SCSS system
-- See `src/styles/README.md` for full documentation
-
-**Build System:**
-- Dual output: CommonJS (`lib/`) and ES modules (`es/`)
-- Gulp-based build pipeline via omni-door
-- SCSS preprocessing with modern API
-- Path aliasing: `@/` maps to `src/`
-
-### Directory Structure
-```
-src/
-├── components/           # All UI components
-│   └── ComponentName/
-│       ├── ComponentName.tsx        # Main component file
-│       ├── interface.ts             # TypeScript interfaces
-│       ├── index.ts                 # Export barrel
-│       ├── style/                   # SCSS styles
-│       │   ├── ComponentName.scss
-│       │   └── index.ts             # (some components)
-│       ├── ComponentName.stories.tsx # Storybook stories (optional)
-│       ├── __test__/                # Jest tests (optional)
-│       └── README.md                # Component documentation (optional)
-├── utils/               # Utility functions (classnames)
-├── styles/              # SCSS design system (tokens, theme, system, utilities)
-│   ├── tokens/          #   Design tokens (color, spacing, radius, shadow, etc.)
-│   ├── theme/           #   Token → CSS variable transformation
-│   ├── system/          #   om-sx mixin, responsive, variant DSL
-│   ├── utilities/       #   Atomic CSS class generator
-│   ├── _api.scss        #   Public API entrypoint for components
-│   └── _settings.scss   #   Global settings
-└── index.ts             # Main library export
-```
-
-> Note: Not all components have stories, tests, or README. The full scaffold (stories + tests + README) is generated by `omni new` but may not exist for manually created components.
-
-### Component Development Patterns
-- **Base Components**: Most components wrap PrimeReact components with custom styling
-- **Props Interface**: Each component has a dedicated `interface.ts` file
-- **Styling**: SCSS with the internal design system (`@use '@/styles/api' as *`), using `classnames` utility for class composition
-- **Testing**: Jest with snapshot testing (currently only Spinner and Icons have tests)
-- **Stories**: Storybook stories for documentation (currently only Spinner and Icons have stories)
-
-### Key Files
-- `omni.config.js`: Main configuration for build, dev server, and scaffolding
-- `gulpfile.js`: Custom build pipeline configuration
-- `tsconfig.json`: TypeScript configuration with path mapping
-- `.storybook/`: Storybook configuration with custom theming
-
-### Package Exports
-The library provides both named exports and individual component imports:
-```js
-// Named imports
-import { Button, Checkbox, Tag, Tooltip, Notification, Icons, Spinner } from '@1money/components-ui';
-
-// Type imports
-import type { ButtonProps, IconName, SpinnerProps } from '@1money/components-ui';
-
-// Individual component imports (tree-shakeable)
-import { Button } from '@1money/components-ui/Button';
-import { Icons, IconWrapper, IconHover } from '@1money/components-ui/Icons';
-
-// CSS (required for styling)
-import '@1money/components-ui/index.css';
-```
-
-**Available components:** Accordion, Alert, Button, Calendar, Carousel, Cell, Checkbox (+ CheckboxGroup), CoachMark, Copy, Dialog, Divider, Drawer, Dropdown, Empty, Flex, Grid (+ Row, Col), Icons (+ IconWrapper, IconHover), Input, Link, Navigation (+ Nav), Notification, Pagination, Popconfirm, Portal, ProForm (unified form system, see below), Progress, Radio (+ RadioGroup), ResizeObserver, Segment, Select, Skeleton, Slider, Space, Spinner, Step, Switch, Table (+ VirtualTable), Tabs, Tag, Tooltip, Tour, Trigger, Typography, Upload (+ UploadFileBar), VirtualList
-
-**ProForm system:** The form layer is consolidated into a single `ProForm` module — there is no standalone `Form` component. `ProForm` wraps a `<form>` element, provides the unified `ProFormContext` (combines form-core state and ProForm semantics), and exposes:
-- `ProForm` (root) with static sub-components: `ProForm.Item`, `ProForm.Dependency`, `ProForm.List`, `ProForm.Group`, `ProForm.FieldSet`, `ProForm.Submitter`, `ProForm.Text / Password / TextArea / Checkbox / CheckboxGroup / Switch / Select / RadioGroup / Slider / DatePicker / Upload`, plus hooks `ProForm.useForm`, `ProForm.useInstance`, `ProForm.useContext`.
-- `ProFormItem` — the public item primitive (supports `transform`, `convertValue`, `valueType`, `readonlyRender`, `colProps`, `mode`, `emptyText`, `valueEnum`).
-- Named exports for all field components, `ProFormDependency`, `ProFormList`, `ProFormGroup`, `DialogForm`, `DrawerForm`, `QueryFilter`, and `createProFormField` (the extension factory).
-- Internal-only: `FormItem` (the low-level item used by `ProFormItem`), `useFormCore`, `FormContext` — none of these are publicly exported.
-
-### Development Workflow
-1. Use `omni new ComponentName -f` to scaffold new components (generates interface, styles, stories, tests, and README)
-2. All components must pass linting (`pnpm lint`) and tests (`pnpm test`) before building
-3. Build process generates both CommonJS and ES module outputs with TypeScript declarations
-4. Storybook (`pnpm dev`) serves as both development environment and documentation
-5. After adding a new component, update `src/index.ts` and `package.json` exports
-
-### Important Notes
-- Font assets (Aeonik, Inter, Outfit) are included in `public/fonts/`
-- Pre-commit hooks enforce code quality via husky and lint-staged
-- Hooks are imported from `@1money/hooks`, not defined locally
-- Styling uses the internal SCSS design system (`src/styles/`), not TailwindCSS
-- Component SCSS files should import `@use '@/styles/api' as *` for access to all design tokens and mixins
-
-## Commit Convention
-
-This project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.
-
-### Commit Message Format
-
-```
-<type>(<scope>): <subject>
-
-[optional body]
-
-[optional footer]
-```
-
-### Types
-
-Allowed types are enforced by `commitlint.config.js`. Use the standard types below:
-
-| Type | Description |
-|------|-------------|
-| `feat` | New feature |
-| `feature` | New feature (alias for `feat`) |
-| `fix` | Bug fix |
-| `hotfix` | Urgent bug fix |
-| `docs` | Documentation changes only |
-| `style` | Code style changes (formatting, missing semicolons, etc.) — no logic change |
-| `refactor` | Code refactoring — no feature addition or bug fix |
-| `test` | Adding or updating tests |
-| `chore` | Build process, tooling, or dependency changes |
-| `revert` | Revert a previous commit |
-| `update` | General updates |
-| `upgrade` | Dependency upgrades |
-| `modify` | Minor modifications |
-| `merge` | Merge commits |
-| `optimize` | Performance or code optimization |
-| `revamp` | Major rework |
-| `refine` | Small refinements |
-
-> Note: `[OMNI-DOOR]` and `[@1MONEY/COMPONENTS-UI]` are also allowed for auto-generated commits by tooling.
-
-### Scope
-
-The scope should be the name of the component or module affected:
-
-```
-feat(Button): add loading state support
-fix(Input): correct placeholder color in dark mode
-docs(ProForm): update usage examples
-refactor(utils): simplify classnames helper
-```
-
-Omit scope when the change is global or cross-cutting:
-
-```
-chore: upgrade PrimeReact to v11
-ci: add lint check to PR workflow
-```
-
-### Subject Rules
-
-- ✅ Use imperative mood: "add feature" not "added feature" or "adds feature"
-- ✅ Start with a lowercase letter
-- ✅ No period at the end
-- ✅ Keep under 72 characters
-- ❌ Do not use vague messages like "fix bug", "update code", "WIP"
-
-### Examples
-
-```bash
-# ✅ Good
-feat(ProForm): add StepsForm component with validation support
-fix(Select): prevent dropdown from closing on internal scroll
-refactor(Button): extract size constants to avoid magic strings
-test(Input): add snapshot tests for controlled mode
-docs(README): add installation and usage guide
-chore: update pnpm lockfile after dependency upgrade
-
-# ❌ Bad
-fix bug
-update
-WIP
-feat: add stuff
-```
-
-### Breaking Changes
-
-Breaking changes must be noted in the footer with `BREAKING CHANGE:`:
-
-```
-feat(ProForm): change onSubmit callback signature
-
-BREAKING CHANGE: onSubmit now receives (values, form) instead of (values).
-Consumers must update their onSubmit handlers accordingly.
-```
-
-### Multi-line Body
-
-Use the body to explain *why* a change was made, not *what* was changed (the diff shows that):
-
-```
-fix(StepsForm): clear downstream step values on backward navigation
-
-When a user navigates backward in a multi-step form, previously entered
-values in later steps should be cleared to prevent stale data from
-being submitted. This matches the expected UX behavior.
-```
-
-## TypeScript Standards
-
-### Core Principles
-
-- ✅ All components and functions must provide accurate type definitions
-- ✅ Avoid using `any`; define types as precisely as possible
-- ✅ Use interfaces (`interface`) instead of type aliases (`type`) for object structures
-- ✅ Export all public interface types for easier consumer usage
-- ✅ Follow TypeScript type design principles strictly to ensure type safety
-- ✅ Ensure compilation has no type errors or warnings
-
-### Component Type Definitions
-
-```tsx
-// ✅ Correct: use interface to define Props
-interface ButtonProps {
-  type?: 'primary' | 'secondary' | 'warning';
-  onClick?: (e: React.MouseEvent) => void;
-}
-
-// ❌ Incorrect: avoid using type to define object structures
-type ButtonProps = {
-  type?: 'primary' | 'secondary';
-};
-
-// ✅ Correct: component Props interface naming
-interface ComponentNameProps {
-  // ...
-}
-
-// ✅ Correct: component state interface naming
-interface ComponentNameState {
-  // ...
-}
-
-// ✅ Correct: use ForwardRefRenderFunction to define ref
-const Component = React.forwardRef<ComponentRef, ComponentProps>((props, ref) => {
-  // ...
-});
-```
-
-### Type Usage Best Practices
-
-- ✅ Use generics where appropriate to improve type flexibility
-- ✅ Use intersection types (`&`) to combine multiple types
-- ✅ Use literal union types to define a limited set of options
-- ✅ Avoid `enum`; prefer union types and `as const`
-- ✅ Rely on TypeScript type inference as much as possible
-- ✅ Use type assertions (`as`) only when necessary
-
-```tsx
-// ✅ Recommended: use union types and as const
-const ButtonTypes = ['primary', 'secondary', 'warning'] as const;
-type ButtonType = (typeof ButtonTypes)[number];
-
-// ❌ Not recommended: use enum
-enum ButtonType {
-  Primary = 'primary',
-  Default = 'secondary',
-}
-```
-
-### Avoid Magic Strings
-
-- ✅ Define string constants or use `as const` arrays for repeated string values
-- ✅ Use constants for event names, action types, storage keys, and API endpoints
-- ✅ Extract hardcoded strings into named constants with descriptive names
-- ✅ Keep constants close to their usage or in a dedicated constants file
-
-```tsx
-// ✅ Correct: define constants
-const STORAGE_KEY = 'user_preferences';
-const EVENT_SUBMIT = 'submit';
-
-localStorage.setItem(STORAGE_KEY, value);
-element.addEventListener(EVENT_SUBMIT, handler);
-
-// ✅ Correct: use as const for related values
-const ToastTypes = ['success', 'error', 'warning', 'info'] as const;
-type ToastType = (typeof ToastTypes)[number];
-
-// ❌ Incorrect: magic strings scattered in code
-localStorage.setItem('user_preferences', value);
-element.addEventListener('submit', handler);
-if (status === 'success') { ... }
-```
-
-## Custom Hooks Usage Guide
-
-Hooks are provided by `@1money/hooks`. Import them as:
-```tsx
-import { useControlledState, useEventCallback } from '@1money/hooks';
-```
-
-**Currently used in this library:** `useControlledState`, `useEventCallback` (in Checkbox and Tooltip).
-
-The following hooks are available and should be used when applicable:
-
-### useControlledState
-
-**When to use**: Building components that support both controlled and uncontrolled modes.
-
-```tsx
-// ✅ Use for form components that can be controlled or uncontrolled
-function Input({ value, defaultValue, onChange }: InputProps) {
-  const [innerValue, setInnerValue] = useControlledState(defaultValue ?? '', value);
-
-  const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
-    setInnerValue(e.target.value);
-    onChange?.(e);
-  };
-
-  return <input value={innerValue} onChange={handleChange} />;
-}
-```
-
-### useEventCallback
-
-**When to use**: When you need a stable callback reference that always invokes the latest function version. Similar to React's `useEvent` RFC.
-
-```tsx
-// ✅ Use when passing callbacks to optimized child components
-function Parent() {
-  const [count, setCount] = useState(0);
-
-  // Stable reference, always calls latest function
-  const handleClick = useEventCallback(() => {
-    console.log('Current count:', count); // Always gets latest count
-  });
-
-  return <MemoizedChild onClick={handleClick} />;
-}
-```
-
-### useLatest
-
-**When to use**: When you need to access the latest value in callbacks without causing re-renders or stale closures.
-
-```tsx
-// ✅ Use to avoid stale closures in timers or event handlers
-function Timer({ delay, callback }: TimerProps) {
-  const callbackRef = useLatest(callback);
-
-  useEffect(() => {
-    const id = setInterval(() => {
-      callbackRef.current(); // Always calls the latest callback
-    }, delay);
-    return () => clearInterval(id);
-  }, [delay]); // No need to include callback in deps
-}
-```
-
-### useLayoutEffect
-
-**When to use**: When you need to know if the effect is running on initial mount or subsequent updates.
-
-```tsx
-// ✅ Use when behavior differs between mount and update
-function AnimatedComponent({ value }: Props) {
-  useLayoutEffect((mount) => {
-    if (mount) {
-      // Initial mount - setup without animation
-      element.style.opacity = '1';
-    } else {
-      // Update - animate the change
-      animateOpacity(element);
-    }
-  }, [value]);
-}
-```
-
-### useMemoizedFn
-
-**When to use**: When you need a stable function reference without managing a dependency array, while always calling the latest version.
-
-```tsx
-// ✅ Use for event handlers passed to child components
-function Form({ onSubmit }: FormProps) {
-  const [data, setData] = useState({});
-
-  // Stable reference, no deps needed, always uses latest data
-  const handleSubmit = useMemoizedFn(() => {
-    onSubmit(data);
-  });
-
-  return <ExpensiveChild onSubmit={handleSubmit} />;
-}
-```
-
-### usePrevious
-
-**When to use**: When you need to compare current value with the previous render's value.
-
-```tsx
-// ✅ Use for detecting value changes
-function Counter({ count }: Props) {
-  const prevCount = usePrevious(count);
-
-  useEffect(() => {
-    if (prevCount !== undefined && count > prevCount) {
-      console.log('Count increased!');
-    }
-  }, [count, prevCount]);
-}
-```
-
-### useSafeState
-
-**When to use**: When setting state in async callbacks where the component might unmount before completion.
-
-```tsx
-// ✅ Use for async operations to prevent memory leaks
-function AsyncComponent() {
-  const [data, setData] = useSafeState<Data | null>(null);
-
-  useEffect(() => {
-    fetchData().then((result) => {
-      setData(result); // Safe: won't update if unmounted
-    });
-  }, []);
-}
-```
-
-### useSyncState
-
-**When to use**: When React batches multiple state updates but you need to read the latest value synchronously.
-
-```tsx
-// ✅ Use when multiple events fire simultaneously (e.g., onTransitionEnd)
-function AnimatedList() {
-  const [getCompletedCount, setCompletedCount] = useSyncState(0);
-
-  const handleTransitionEnd = () => {
-    // Multiple transitions may end at once, React batches them
-    // getCompletedCount() always returns the latest value
-    setCompletedCount(getCompletedCount() + 1);
-  };
-}
-```
-
-### useUpdateEffect
-
-**When to use**: When you want an effect to run only on updates, skipping the initial mount.
-
-```tsx
-// ✅ Use when initial render shouldn't trigger the effect
-function SearchInput({ query, onSearch }: Props) {
-  useUpdateEffect(() => {
-    // Only runs when query changes, not on initial mount
-    onSearch(query);
-  }, [query]);
-}
-```
-
-### useLayoutState
-
-**When to use**: When you need to batch multiple synchronous state updates into a single microtask to reduce unnecessary re-renders. Updates are collected and applied together via `Promise.resolve`, triggering only one render.
-
-```tsx
-// ✅ Use when multiple state updates happen synchronously and should be batched
-function VirtualTable({ columns }: Props) {
-  const [colWidths, setColWidths] = useLayoutState<Map<string, number>>(new Map());
-
-  const handleResize = (key: string, width: number) => {
-    // Multiple columns may resize at once; updates are batched into one render
-    setColWidths(prev => new Map(prev).set(key, width));
-  };
-
-  return <ResizableColumns widths={colWidths} onResize={handleResize} />;
-}
-```
-
-### useTimeoutLock
-
-**When to use**: When you need a short-lived lock that auto-resets after a timeout (100ms). Useful for preventing duplicate actions or debouncing rapid state changes.
-
-```tsx
-// ✅ Use to prevent rapid duplicate submissions
-function SubmitButton() {
-  const [setLock, getLock] = useTimeoutLock<string>();
-
-  const handleClick = () => {
-    if (getLock()) return; // Already locked
-    setLock('submitting');
-    submitForm();
-  };
-}
-```
-
-### Hook Selection Guide
-
-| Scenario | Recommended Hook |
-|----------|------------------|
-| Controlled/uncontrolled component | `useControlledState` |
-| Stable callback for memoized children | `useEventCallback` or `useMemoizedFn` |
-| Access latest value without re-render | `useLatest` |
-| Different logic for mount vs update | `useLayoutEffect` |
-| Compare with previous value | `usePrevious` |
-| Async state updates after unmount | `useSafeState` |
-| Read latest state synchronously | `useSyncState` |
-| Skip effect on initial mount | `useUpdateEffect` |
-| Batch synchronous state updates | `useLayoutState` |
-| Short-lived lock with auto-reset | `useTimeoutLock` |

package/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

package/jest.setup.d.ts

@@ -1 +0,0 @@
-import '@testing-library/jest-dom';

package/jest.setup.ts

@@ -1 +0,0 @@
-import '@testing-library/jest-dom';