@faststore/components 4.1.0-dev.1 → 4.1.0-dev.11

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <a href="https://faststore.dev">
+  <a href="https://developers.vtex.com/docs/guides/faststore">
     <img alt="Faststore" src="../ui/static/logo.png" width="60" />
   </a>
 </p>
@@ -8,15 +8,95 @@
 </h1>
 <p align="center">
   <strong>
-  FastStore UI components without style layer.
+    FastStore UI components without a style layer
   </strong>
 </p>
-
-<div style="display: flex; justify-content: center; width: 100%">
-  <a href="https://www.npmjs.com/package/@faststore/components" style="padding: 0px 2px 0px 0px">
-    <img src="https://badge.fury.io/js/%40faststore%2Fui.svg" />
-  </a>
-  <a href="https://bundlephobia.com/package/@faststore/components" style="padding: 0px 0px 0px 2px">
-    <img src="https://badgen.net/bundlephobia/dependency-count/@faststore/components" />
+<p align="center">
+  <a href="https://www.npmjs.com/package/@faststore/components">
+    <img src="https://badge.fury.io/js/%40faststore%2Fcomponents.svg" alt="npm version" />
   </a>
-</div>
+</p>
+
+`@faststore/components` provides the structure, logic, and accessibility of FastStore UI components — without any styling. It organizes the components into atoms, molecules, and organisms.
+
+Styling is handled separately by `@faststore/ui`, which consumes this package and applies design tokens and structural SCSS on top of the data attributes defined here.
+
+## Package structure
+
+```text
+src/
+├── atoms/       # Basic building blocks (Button, Input, Badge, Icon, etc.)
+├── molecules/   # Composite components (Accordion, CartItem, ProductCard, etc.)
+├── organisms/   # Complex feature components (Hero, Filter, ProductShelf, etc.)
+├── hooks/       # UI state hooks (useSlider, useSearch, useTrapFocus, etc.)
+├── typings/     # Shared TypeScript types
+└── index.ts     # Public exports
+test/
+└── molecules/   # Component tests (incomplete — see note below)
+```
+
+> **Note:** Test coverage is currently incomplete. Tests should live in `test/{category}/{ComponentName}/` for all atoms, molecules, and organisms. Contributions adding missing test coverage are welcome.
+
+
+## How to run
+
+### Prerequisites
+
+- Node.js ≥ 20
+- pnpm
+
+### Local setup
+
+```bash
+# 1. Install dependencies (from the repo root)
+pnpm install
+
+# 2. Start the build in watch mode
+pnpm dev
+```
+
+## How to develop
+
+### Adding a new component
+
+1. **Categorize** the component: atom, molecule, or organism
+2. **Create** `src/{category}/{ComponentName}/{ComponentName}.tsx` and `index.ts`
+3. **Use data attributes** for styling hooks — no style imports in this package:
+   ```tsx
+   <div
+     data-fs-badge            // root identifier
+     data-fs-badge-size={size} // state attribute
+   >
+     {children}
+   </div>
+   ```
+4. **Export** from `src/index.ts`
+5. **Add styles** in `@faststore/ui` using the data attributes as selectors
+6. **Write tests** in `test/{category}/{ComponentName}/`
+
+> For the full implementation checklist (accessibility, props interface, composability guidelines), refer to the [Component Implementation Guidelines](../../AGENTS.md#-faststore-components-implementation-guidelines) in `AGENTS.md`.
+
+### Data attribute naming convention
+
+| Context | Pattern | Example |
+| :--- | :--- | :--- |
+| Root element | `data-fs-{component}` | `data-fs-badge` |
+| Internal structure | `data-fs-{component}-{part}` | `data-fs-badge-wrapper` |
+| State | `data-fs-{component}-{state}={value}` | `data-fs-button-variant="primary"` |
+
+## How to test
+
+```bash
+pnpm test
+```
+
+For interactive visual testing, use Storybook. Run `pnpm dev` from `packages/storybook/` to launch it.
+
+## How to publish
+
+Versioning and publishing are managed at the monorepo root by Lerna. Do not publish this package independently. Refer to the [Contributing guidelines](../../CONTRIBUTING.MD) for the full release workflow.
+
+## Documentation
+
+- **Component reference:** [developers.vtex.com/docs/guides/faststore/components-index](https://developers.vtex.com/docs/guides/faststore/components-index)
+- **Implementation guidelines:** [`AGENTS.md`](../../AGENTS.md#-faststore-components-implementation-guidelines)

package/package.json

@@ -1,14 +1,9 @@
 {
   "name": "@faststore/components",
-  "version": "4.1.0-dev.1",
+  "version": "4.1.0-dev.11",
   "main": "dist/cjs/index.js",
   "module": "dist/es/index.mjs",
   "typings": "dist/index.d.ts",
-  "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build",
-    "test": "vitest run"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -26,28 +21,29 @@
     "directory": "packages/components"
   },
   "peerDependencies": {
-    "react": "catalog:",
-    "react-dom": "catalog:",
-    "tabbable": "catalog:"
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "tabbable": "5.2.1"
   },
   "dependencies": {
-    "react-intersection-observer": "catalog:",
-    "react-swipeable": "catalog:"
+    "react-intersection-observer": "^8.32.5",
+    "react-swipeable": "^7.0.0"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "catalog:",
+    "@testing-library/react": "14.3.1",
     "@types/papaparse": "^5.5.0",
-    "@types/react": "catalog:",
-    "@types/react-dom": "catalog:",
-    "@types/tabbable": "catalog:",
+    "@types/react": "^18.3.27",
+    "@types/react-dom": "^18",
+    "@types/tabbable": "^3.1.1",
+    "@vitest/coverage-v8": "4.0.7",
     "papaparse": "^5.5.3",
     "react-dropzone": "^14.3.8",
-    "tabbable": "catalog:",
-    "tslib": "catalog:",
-    "vite": "catalog:",
-    "vite-plugin-dts": "catalog:",
-    "vitest": "catalog:",
+    "tabbable": "5.2.1",
+    "tslib": "2.8.1",
+    "vite": "7.1.5",
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "4.0.7",
     "vitest-axe": "^0.1.0"
   },
   "engines": {
@@ -56,5 +52,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "05674217b8f15f6fa8aa4d84148ab18f03a55c66"
-}
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/molecules/Toast/Toast.tsx

@@ -5,7 +5,7 @@ import { useUI } from '../../hooks'
 function Toast() {
   const { toasts, popToast } = useUI()
   const toast = toasts[toasts.length - 1]
-  const timeoutRef = useRef<number>()
+  const timeoutRef = useRef<ReturnType<typeof setTimeout>>()
 
   const [visible, setVisible] = useState(false)