@1money/component-ui 0.0.1

package/AGENTS.md

@@ -0,0 +1,540 @@
+# 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:** Button, Checkbox, Tag, Tooltip, Notification, Icons (+ IconWrapper, IconHover), Spinner
+
+### 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

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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1Money Co
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.