forstok-ui-lib 8.3.11 → 8.3.13

package/.agent/README.md

@@ -0,0 +1,15 @@
+# .agent Working Memory
+
+Purpose: persistent, AI-friendly notes about this repo so future agents can ramp quickly without re-scanning the codebase.
+
+How to use:
+- Read `repository-summary.md` and `architecture-overview.md` first for context, then `module-map.md`, `frontend-flow.md`, `backend-flow.md` (if present), and `env-map.md` before coding.
+- Consult `coding-conventions.md` to match existing style and `risk-register.md` to avoid regressions.
+- For specific tasks, jump to `task-entrypoints.md`, `feature-prompts.md`, or `bugfix-prompts.md`.
+- Update `change-log.md` whenever you modify code or these docs.
+
+Update rules:
+- Keep docs grounded in actual code; mark assumptions explicitly.
+- Never store secrets, credentials, or tokens here.
+- When adding features/fixes, refresh relevant sections (flows, module map, risks, tests) and append a dated note to `change-log.md`.
+- If something is unclear, record questions in `open-questions.md`.

package/.agent/api-map.md

@@ -0,0 +1,3 @@
+# API Map
+
+Not applicable: no HTTP endpoints or API clients are defined in this library. Components expose props/callbacks only.

package/.agent/app-workflows.md

@@ -0,0 +1,13 @@
+# App Workflows
+
+This repository is a component library, not a runnable app. Workflows refer to component usage patterns:
+
+- **Select flow**: `SelectComponent` wraps `react-select`/`CreatableSelect`, manages value state, supports multi-select, custom labels/options, async paginate menu lists, and guarded removals (confirm via message question). Emits `evChange` and optional form-field `evChangeCustom` callbacks.
+- **Input flow**: `InputComponent` handles text/number/currency inputs with formatting (`formatNumber`), reset/force-update flags, Enter-key handlers, and form-field callbacks.
+- **Date/DateTime flow**: date pickers (moment + react-datepicker/@wojtekmaj/react-daterange-picker) expose refs, typed props, and custom styles; defaults provided in `maps/common.ts`.
+- **Popup & Message flow**: `PopupComponent` renders modal/question overlays with head/body/foot slots; `MessageComponent` renders toast-like notifications with timers and callbacks; helper functions generate typed message payloads.
+- **Table/List flow**: components expect children annotated via `aria-label` (head/body/foot) to auto-build rows/columns; supports force-update flag for controlled rerender.
+- **Upload flow**: file/image upload components manage drag/drop and thumbnail display using shared CSS patterns.
+- **Emoji & Icon flow**: wraps `frimousse` emoji picker and SVG/icon usage.
+
+Assumption: consuming apps orchestrate business logic, pass data/handlers into these components, and provide theme variables.

package/.agent/architecture-overview.md

@@ -0,0 +1,10 @@
+# Architecture Overview
+
+- **Pattern**: Monorepo-less, single package React component library. No backend/services. All logic resides in front-end components and shared helpers.
+- **Exports**: `src/index.ts` aggregates `components`, `assets`, `typeds`, and `maps` for external consumption.
+- **Styling**: styled-components with heavy use of CSS variables (expects host app to define theme tokens such as `--pri-clr`, `--sec-clr-bg`). Some CSS modules imported via `rollup-plugin-import-css`.
+- **State & hooks**: React functional components; some use `use-state-with-callback` for post-set callbacks. Utilities rely on browser globals (`window`, `document`, storage), implying browser-only usage (no SSR safety guards).
+- **External integrations**: UI dependencies only (react-select, react-datepicker, moment, approvejs for validation, html-to-text, frimousse emoji picker). No HTTP/API layers.
+- **Data/config**: `src/maps/common.ts` provides default date range presets using moment.
+- **Build pipeline**: Rollup builds CJS + ESM bundles and separate DTS bundle. Peer deps externalized. Styled-components transformer injects component IDs and display names.
+- **Background/queue/cron**: None.

package/.agent/backend-flow.md

@@ -0,0 +1,3 @@
+# Backend Flow
+
+Not applicable: this repository ships frontend components only. There is no server code, routing, middleware, database access, background jobs, or API clients. Any backend interactions occur in consuming applications, not here.

package/.agent/bugfix-prompts.md

@@ -0,0 +1,19 @@
+# Bugfix Prompt Templates
+
+- **General bug investigation**
+  "Investigate bug in <ComponentName>. Reproduce with prop/state combo. Inspect src/components/<name>/index.tsx and related styles/helpers. Check `reset`/`isForceUpdate` handling and event callbacks."
+
+- **Root cause analysis**
+  "Trace the failing behavior in <ComponentName>. Map input props → internal state → rendered output. Verify helper usage (formatNumber, generateMessageQuestion, etc.) and external deps. Document findings in .agent/change-log.md."
+
+- **Safe fix with minimal regression**
+  "Implement minimal change to fix <issue> in <ComponentName>. Avoid altering public prop shapes; add guards/tests if possible. Update types and styles only where necessary."
+
+- **Query/formatting bug fix**
+  "Fix data formatting or color/status mapping in src/assets/javascripts/helper.ts or function.ts. Keep return types and callers intact."
+
+- **API (prop) bug fix**
+  "Adjust prop handling for <prop> in <ComponentName>. Ensure defaults and optional props are preserved. Update typed.ts if required."
+
+- **Frontend UI bug fix**
+  "Correct UI glitch in <ComponentName> styles (src/components/<name>/styles.ts). Verify CSS variables and responsive rules. Keep DOM structure stable for consumers."

package/.agent/change-log.md

@@ -0,0 +1,3 @@
+# Change Log
+
+- 2026-03-09: Created .agent documentation set summarizing repository structure, architecture, workflows, risks, and task prompts. No code changes beyond docs.

package/.agent/coding-conventions.md

@@ -0,0 +1,11 @@
+# Coding Conventions
+
+- **Language**: TypeScript with React functional components; strict mode in tsconfig.
+- **Styling**: styled-components; props often prefixed with `$` to avoid DOM leakage and drive style variants. CSS variables expected from host (e.g., `--pri-clr`, `--sec-clr-bg`). Shared CSS fragments live in `src/assets/stylesheets` and `components/*/styles.ts`.
+- **State**: `useState` and `use-state-with-callback` for cases needing post-set callbacks; components expose `isForceUpdate`/`setForceUpdate` and `reset/setReset` flags for parent-controlled resets.
+- **Events**: callbacks prefixed with `ev*` (e.g., `evChange`, `evCreateMessage`); form-field updates use `evChangeCustom(name, value)` when `isField` is true.
+- **Data typing**: shared types in `src/typeds` (`TObject`, `TState`, `TOption`, etc.). Component-specific `typed.ts` files accompany components with complex props.
+- **Error handling**: UI-level guards (e.g., disable actions, prevent deletion below min count); uses helper validation via `approvejs` in utilities, but no central error boundary.
+- **Logging**: none in codebase; rely on UI cues instead of console logging.
+- **Formatting/number handling**: helpers like `formatNumber`, `currencyNumber`, `generateValue`, and multiple color/status mappers in `assets/javascripts`.
+- **Structure**: components often rely on child `aria-label` markers to organize slots (table, popup, message).

package/.agent/database-map.md

@@ -0,0 +1,3 @@
+# Database Map
+
+Not applicable: no database, ORM, or queries exist in this UI library.

package/.agent/deployment-notes.md

@@ -0,0 +1,8 @@
+# Deployment Notes
+
+- **Artifact**: Built with rollup into `dist/index.js` (CJS), `dist/index.mjs` (ESM), and `dist/index.d.ts` (types).
+- **Build command**: `npm run build`.
+- **Publish**: likely published to npm (`npm publish`) after bumping version (`npm version [patch|minor|major]`), as hinted in README.
+- **CI/CD**: No CI config present in repo.
+- **Runtime assumptions**: Browser environment with CSS variables defined by host app; React 19 and styled-components 6 provided as peer deps.
+- **Bundling details**: Peer deps externalized; assets (images) emitted to `dist/images`; styled-components transformer enabled for better class names.

package/.agent/env-map.md

@@ -0,0 +1,4 @@
+# Env Map
+
+- No environment variables are referenced in the codebase.
+- Assumptions: consuming applications provide any necessary API keys/config; this library only depends on browser globals (`window`, `document`, `localStorage`, `sessionStorage`).

package/.agent/feature-prompts.md

@@ -0,0 +1,19 @@
+# Feature Prompt Templates
+
+- **Add new component**
+  "You are updating forstok-ui-lib. Goal: add a new <ComponentName> under src/components/<name>. Review coding style in src/components/<similar>/ and exports in src/components/index.ts + src/index.ts. Provide styled-components styles, typed props, and ensure no breaking API changes. Include usage notes and build updates."
+
+- **Update existing component behavior**
+  "Modify <ComponentName> in src/components/<name>/ to <desired change>. Preserve existing props and `reset/isForceUpdate` patterns. Update types in typed.ts if needed and adjust styles carefully."
+
+- **Change business/UI flow**
+  "Adjust component flow for <scenario> (e.g., Select removal confirmation). Identify callbacks (`evChange`, `evCreateMessageQuestion`) and update logic in index.tsx plus helper utilities if necessary. Document risks and update .agent/change-log.md."
+
+- **Add endpoint-like utility**
+  "Add new helper in src/assets/javascripts/function.ts for <purpose>. Keep pure/browser-safe, add type definitions, and ensure exports."
+
+- **Update database query**
+  "N/A (no DB). If needing data shaping, modify helper functions only and keep types in sync."
+
+- **Refactor module**
+  "Refactor <module> for clarity/performance without changing public API. Maintain prop names, CSS variable expectations, and ensure build passes."

package/.agent/frontend-flow.md

@@ -0,0 +1,9 @@
+# Frontend Flow
+
+- **Routing**: None defined; components are framework-agnostic React pieces for host apps to compose.
+- **Component hierarchy**: Flat exports; each component encapsulates its own styles. Some components (Popup, Table, List) rely on children with specific `aria-label` markers to render sections.
+- **Data fetching**: Not included. Components accept data via props (e.g., `options` for Select, `data` for lists/tables).
+- **State management**: Local React state with optional externally controlled flags (`reset`, `isForceUpdate`). No global state/store included.
+- **Forms**: Inputs/Selects support `isField` and `evChangeCustom(name, value)` to integrate with form management; `evEnter` for Enter-key submissions; currency/number formatting helpers used during key events.
+- **UI patterns**: Styled-components for theming; extensive use of CSS variables; modal overlay pattern via Popup/Message; skeleton loaders via Loader/Loading; select dropdown custom styling consistent across modes.
+- **Reusable components**: Buttons, Inputs (including OTP and ref-forwarding), Select variants, Date/Datetime pickers, Upload drag/drop, Emoji picker, Table/List layouts, Icon set, Popup/Message utilities.

package/.agent/module-map.md

@@ -0,0 +1,30 @@
+# Module Map
+
+- `src/index.ts`: central export barrel for components, assets, typeds, maps.
+- `src/components/`: React components.
+  - `button/`: styled button variants with optional arrow indicator.
+  - `checkbox/`, `radio/`, `switch/`: form controls with custom styles.
+  - `input/`: text/number/currency input, OTP variant, ref-forwarding variant.
+  - `textarea/`: textarea with ref variant.
+  - `select/`: react-select wrappers (standard, async paginate, creatable, select-all, custom menu list, helper functions & types).
+  - `dropdown/`: simple dropdown container + styles.
+  - `date/`, `datetime/`: date/datetime pickers, refs, typed helpers, styles.
+  - `label/`, `text/`, `link/`: typography helpers and link styles.
+  - `list/`, `table/`: list/table layout components using children slots.
+  - `popup/`, `message/`: modal/toast messaging infrastructure with typed helpers.
+  - `portal/`: React portal wrapper.
+  - `icon/`: icon renderer with typed icon names.
+  - `image/`, `upload/`: image display and upload drag-drop UI.
+  - `emoji/`: emoji picker component.
+  - `loader/`, `loading/`: loading indicators/skeletons.
+  - `form/styles.ts`, `date/styles.ts`, `dropdown/styles.ts`, `select/styles.ts`: shared styled-components fragments exposed for consumer styling.
+- `src/assets/`:
+  - `stylesheets/`: `bases.styles.ts` and `shares.styles.ts` reusable CSS snippets.
+  - `javascripts/`: helper utilities (`function.ts`, `helper.ts`).
+  - `images/`: placeholder assets/icons used by styles.
+- `src/typeds/`: shared types (`base.typed.ts`, `shares.typed.ts`) used across components.
+- `src/maps/`: `common.ts` config constants (date range defaults) exported via `index.ts`.
+- `dist/`: generated build artifacts.
+- `grunch`: text pointer file (non-functional).
+
+Safe-to-change: docs in `.agent/`, new components/types under `src/components`/`src/typeds` (ensure exports added). Sensitive: existing component APIs/props used by consuming apps—avoid breaking prop names/shapes; CSS variable expectations; dist artifacts (regenerate via build instead of editing).

package/.agent/open-questions.md

@@ -0,0 +1,6 @@
+# Open Questions
+
+- Are there official theming guidelines or a CSS variable contract for host apps? (CSS vars referenced but not documented here.)
+- Which consuming apps rely on specific component props/modes? Lacking compatibility matrix makes API changes risky.
+- Should SSR compatibility be added, or is browser-only acceptable for all consumers?
+- Any plan for adding automated tests or CI before further changes?

package/.agent/repository-summary.md

@@ -0,0 +1,18 @@
+# Repository Summary
+
+- **Name**: forstok-ui-lib (UI component library for Forstok apps).
+- **Tech stack**: React 19 + TypeScript 5, styled-components 6, react-select, react-datepicker, moment, rollup bundling. No backend/server code.
+- **Purpose**: reusable UI components (inputs, selects, date pickers, loaders, popups, tables, etc.) plus helper utilities and shared types for Forstok frontends.
+- **Key folders**:
+  - `src/components/`: React components grouped by feature (button, input, select, popup, table, etc.).
+  - `src/assets/`: shared styles (styled-components css fragments), helper JS utilities, images.
+  - `src/typeds/`: shared TypeScript types.
+  - `src/maps/`: common config constants (date range defaults).
+  - `dist/`: built output (CJS/ESM/types) — generated, do not edit.
+  - `grunch`: text reference file (YouTube link), unused in build.
+- **Entrypoint**: `src/index.ts` re-exports components, assets, typeds, and maps for consumers.
+- **Build**: `npm run build` (rollup, outputs to `dist/`).
+- **Tests**: none (`npm test` exits with error placeholder).
+- **Lint/format**: none configured.
+- **Install**: `npm install` (preinstall rewrites lock via `npm-force-resolutions`).
+- **System shape**: single-package UI library; no runtime services, APIs, or databases.

package/.agent/risk-register.md

@@ -0,0 +1,9 @@
+# Risk Register
+
+- **API/prop stability**: Consumers depend on current prop names and `$`-prefixed styling flags; breaking changes will ripple across multiple apps.
+- **Browser globals**: Helpers and components access `window`, `document`, and storage directly—unsafe for SSR/Node; changes should preserve browser-only assumptions or add guards.
+- **CSS variable reliance**: Styling expects host-defined CSS vars; altering names/defaults can break theming.
+- **Absence of tests**: No automated coverage; regressions in interactive components (Select, Input, Popup, Table, Upload) are likely if behavior changes.
+- **State flags**: `reset`/`isForceUpdate` patterns used across components; incorrect handling could desync UI state.
+- **Dependencies**: Third-party components (react-select, react-datepicker, moment-range) influence bundle size and behavior; updates may introduce breaking changes.
+- **Accessibility**: Custom controls may not meet accessibility expectations (keyboard focus management limited); modifying markup requires care.

package/.agent/task-entrypoints.md

@@ -0,0 +1,9 @@
+# Task Entrypoints
+
+- **Add a new component**: Create under `src/components/<name>/`, add styles/typed as needed, and export from `src/components/index.ts` plus `src/index.ts` if new barrel export required.
+- **Enhance existing component**: Start in its folder (e.g., `src/components/select/`), inspect `typed.ts` for props and `styles.ts` for theming contracts; consider impacts on shared helpers (`assets/javascripts`).
+- **Adjust shared styles**: `src/assets/stylesheets/` for CSS fragments; `components/*/styles.ts` for component-specific styling.
+- **Modify utilities**: `src/assets/javascripts/function.ts` and `helper.ts` contain formatting, storage, and color/status mappers.
+- **Update shared types**: `src/typeds/` (avoid breaking API unless coordinated with consumers).
+- **Change exports**: keep barrel files (`src/components/index.ts`, `src/index.ts`) in sync.
+- **Build/publish**: run `npm run build`; bump version before publish.

package/.agent/testing-map.md

@@ -0,0 +1,6 @@
+# Testing Map
+
+- Test framework: none configured. `npm test` exits with an error placeholder.
+- Existing coverage: none.
+- Gaps: all components lack automated tests; manual verification required when changing props, styles, or behavior.
+- Recommended: add component-level tests (React Testing Library) and visual regression coverage for high-traffic components (Select, Input, Popup, Table) before making risky changes.

package/dist/index.d.ts

@@ -304,6 +304,7 @@ type TChannel = {
     icon?: string | null;
     id?: number | null;
     totalStores?: number;
+    phone?: string;
     Stores?: {
         id?: number;
         storeName?: string;
@@ -396,7 +397,7 @@ type TInList = TInPart & {
     evClickCollapse?: TMouseEvent;
     isReadyQuery: boolean;
 };
-type TInlistPart = Omit<TInList, 'evClickTab' | 'activePageOption' | 'evSetPageOption' | 'activePage' | 'evSetPage' | 'activeCursor' | 'searchInput' | 'abortRef' | 'abortSecRef' | 'isResetSubscription' | 'isReadyQuery'> & {
+type TInlistPart = Omit<TInList, "evClickTab" | "activePageOption" | "evSetPageOption" | "activePage" | "evSetPage" | "activeCursor" | "searchInput" | "abortRef" | "abortSecRef" | "isResetSubscription" | "isReadyQuery"> & {
     pageEl: JSX.Element | null;
     readyFilter?: string[];
     parseSetForceUpdate?: (value: boolean) => void;
@@ -409,7 +410,7 @@ interface TPagination {
     evSetPage: TMouseEvent;
     activePageOption?: number;
     evSetPageOption: TMouseEvent;
-    mode?: 'noPageOption' | 'min10PageOption';
+    mode?: "noPageOption" | "min10PageOption";
 }
 type TObjPage = {
     cursor?: string;
@@ -467,7 +468,7 @@ type TDetailNew<TData = never> = {
 type Callback<S> = (state: S) => void | (() => void | undefined);
 type DispatchWithCallback<A, S> = (value: A, callback: Callback<S>) => void;
 type TStateCallback<TData> = DispatchWithCallback<React.SetStateAction<TData>, TData>;
-type ModeListTableColumn = 'item' | 'item-nocheck' | 'quantity' | 'listing' | 'listing-nocheck' | 'picklist' | 'package' | 'shipment' | 'invoice' | 'payment-receive' | 'sales-return' | 'activity' | 'putaway' | 'inbound' | 'lowstock' | 'price' | 'stock-adjustment' | 'stock-outbound' | 'stock-transfer' | 'promotion' | 'stock-history' | 'price-history' | 'turnover' | 'days-outofstock' | 'warehouses' | 'archived' | 'pos-order' | 'order' | 'order-nocheck' | 'table-customheader';
+type ModeListTableColumn = "item" | "item-nocheck" | "quantity" | "listing" | "listing-nocheck" | "picklist" | "package" | "shipment" | "invoice" | "payment-receive" | "sales-return" | "activity" | "putaway" | "inbound" | "lowstock" | "price" | "stock-adjustment" | "stock-outbound" | "stock-transfer" | "promotion" | "stock-history" | "price-history" | "turnover" | "days-outofstock" | "warehouses" | "archived" | "pos-order" | "order" | "order-nocheck" | "table-customheader";
 type TInDetail = TInPart & {
     firstDispatch?: Dispatch<any>;
     resetByOption: (opt?: string | string[], callback?: () => void, noScroll?: boolean) => void;
@@ -483,9 +484,9 @@ type TInDetailProps = {
     tabDef?: string;
     hasSubscription?: boolean;
 };
-type modeTable = 'picklist' | 'listing' | 'price' | 'price' | 'price-full' | 'price-mid';
-type BodyContentStyle = 'create-return' | 'create-price' | 'create-adjustment' | 'create-outbound' | 'confirm-inbound' | 'confirm-outbound' | 'confirm-adjustment';
-type BodyContentMode = BodyContentStyle | 'create-promotion' | 'create-inbound' | 'create-transfer' | 'create-picklist' | 'edit-picklist' | 'create-package' | 'edit-master' | 'putaway-inbound' | 'create-paymentreceive' | 'create-master' | 'create-listing' | 'create-adjustment' | 'edit-listing';
+type modeTable = "picklist" | "listing" | "price" | "price" | "price-full" | "price-mid";
+type BodyContentStyle = "create-return" | "create-price" | "create-adjustment" | "create-outbound" | "confirm-inbound" | "confirm-outbound" | "confirm-adjustment";
+type BodyContentMode = BodyContentStyle | "create-promotion" | "create-inbound" | "create-transfer" | "create-picklist" | "edit-picklist" | "create-package" | "edit-master" | "putaway-inbound" | "create-paymentreceive" | "create-master" | "create-listing" | "create-adjustment" | "edit-listing";
 
 declare const InputOTPComponent: ({ otpLength, value, onChange, ...props }: {
     otpLength: number;