cekat-ui 1.2.9 → 1.3.1

package/README.md

@@ -3,105 +3,186 @@
 A modern, lightweight **React UI component library** built with **TypeScript**, **Tailwind CSS**, and **Storybook**.
 
 `cekat-ui` is designed to be:
-- ✅ Composable (shadcn / Radix-inspired)
-- ✅ Tree-shakeable
-- ✅ Fully typed
-- ✅ Framework-agnostic (works with Next.js, Vite, CRA, etc.)
+
+- Composable (compound components, Radix / react-aria-inspired)
+- Tree-shakeable (ESM + UMD, fully typed)
+- Framework-friendly (Next.js, Vite, and other React 18 apps)
+
+This repo uses **Yarn Classic** (`yarn.lock` v1).
 
 ---
 
-## ✨ Features
+## Features
+
+Public exports from `cekat-ui`:
+
+| Area               | Components                                                                                                                                                                                                  |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Actions & feedback | `Button`, `Toggle`, `Checkbox`, `RadioGroup` / `RadioGroupItem`, `Tooltip`, `Alert`, `Loading`, `Dropdown`                                                                                                  |
+| Display            | `Avatar`, `AvatarGroup`, `AvatarLabelGroup`, `AvatarProfilePhoto`, `Badge`, `BadgeGroup`, `Tag`                                                                                                             |
+| Navigation         | `Tab` / `TabList`, `TabBrowser` / `TabBrowserBar`                                                                                                                                                           |
+| Inputs             | `Input` (compound `Input.Prefix` / `Input.Suffix`), `PhoneInput`, `CardNumberInput`, `SaleAmountInput`, `InputCounter`, `Textarea`, `MultiSelectInput`, `InputDropdown`, `WebsiteInput`, `WebsiteCopyInput` |
 
-- Button (compound component)
-- Checkbox
-- Radio Group
-- Toggle (Switch)
-- Tooltip
-- Tailwind CSS styling
+Icons used in stories and examples come from [`@tabler/icons-react`](https://tabler.io/icons).
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 npm install cekat-ui
+# or
+yarn add cekat-ui
+```
 
-or
+Peer dependencies:
 
-yarn add cekat-ui
+```json
+{
+  "react": "^18.3.1",
+  "react-dom": "^18.3.1"
+}
 ```
 
+---
+
 ## Styles
 
-`cekat-ui` ships with prebuilt styles. Import once in your app entry file.
+`cekat-ui` ships prebuilt CSS. Import it once in the app entry file. The file includes component styles and base typography (Nunito); it does not fetch remote fonts.
 
-Next.js (App Router):
-```ts
+Next.js App Router (`app/layout.tsx`):
+
+```tsx
 import 'cekat-ui/style.css';
+```
 
+Next.js Pages Router (`pages/_app.tsx`):
 
+```tsx
+import 'cekat-ui/style.css';
+```
+
+### Tailwind preset
+
+To use design tokens (`primary`, `bg-primary-50`, loading keyframes, and so on) in your own Tailwind classes, add the published preset:
+
+```js
+// tailwind.config.js / tailwind.config.cjs
+module.exports = {
+  presets: [require('cekat-ui/tailwind-preset')],
+  content: ['./app/**/*.{js,ts,jsx,tsx}', './components/**/*.{js,ts,jsx,tsx}'],
+};
+```
+
+`style.css` is enough for component appearance. The preset is for token classes in the consuming app. A working Next 14 example lives in `fixtures/next-consumer`.
+
+---
 
 ## Usage
 
 ### Button
+
+`Button` is built on [React Aria Components `Button`](https://react-aria.adobe.com/Button). Use `onPress` for mouse, touch, and keyboard. `isPending` keeps the control focusable, blocks further presses, and announces progress. `onClick` and `disabled` still work as aliases for `onPress` and `isDisabled`.
+
 ```tsx
 import { Button } from 'cekat-ui';
 
 export default function Example() {
   return (
-    <Button size="md" tone="primary" variant="solid">
-      Click me
+    <Button size="md" tone="primary" variant="solid" onPress={() => save()}>
+      Save
     </Button>
   );
 }
 ```
 
 ### Compound usage
+
 ```tsx
+import { IconChevronLeft } from '@tabler/icons-react';
+import { Button } from 'cekat-ui';
+
 <Button>
   <Button.Icon>
-    <IconChevronLeft size={16} />
+    <IconChevronLeft />
   </Button.Icon>
   <Button.Text>Submit</Button.Text>
-</Button>
+</Button>;
+```
+
+`Button.Icon` sizes the glyph from `size` (xs 18 · sm/md 20 · lg 24 · xl/2xl 28). Omit `size` on the icon.
+
+`Button` sizes: `xs` | `sm` | `md` | `lg` | `xl` | `2xl`. Tone: `primary` | `destructive`. Variants include `solid`, `outline`, `ghost`, and `plain` / `plain-black` (link-style: hug content, 4px gap, no padding or radius).
+
+### Input
+
+```tsx
+import { Input } from 'cekat-ui';
+
+<Input placeholder="Search" />;
 ```
 
+---
+
 ## Components API
 
-All components support:
-- `className` override
-- Controlled & uncontrolled usage
-- Keyboard & screen reader accessibility
-- Size variants (`sm`, `md`, `lg`)
+Most components accept `className` overrides. Sizes, variants, and controlled vs uncontrolled usage differ per component — they are not a single shared API.
 
-For full props reference, see Storybook.
+For full props, variants, and interaction examples, use Storybook.
+
+---
 
 ## Storybook
 
-Run Storybook locally:
 ```bash
-yarn dev
+yarn dev              # http://localhost:6006
+yarn build:storybook  # static build → storybook-static/
 ```
 
-Build static Storybook:
+---
+
+## Testing
+
+Stories are component tests via [Storybook's Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon). They run in Playwright Chromium (browser mode).
+
 ```bash
-yarn build:storybook
+# Watch (starts Storybook for failure links when it is not already running)
+yarn test-storybook
+
+# Single run (CI)
+yarn test-storybook --run
 ```
 
-## Peer Dependencies
+Install browser binaries once with `yarn playwright install chromium`. In Storybook, use the testing widget to run or watch the same tests.
 
-```json
-{
-  "react": ">=18",
-  "react-dom": ">=18"
-}
+Smoke tests cover every story; interaction tests run any story `play` function. Button contracts live in `stories/Button.behaviors.stories.tsx` (press, disabled, pending chrome, icon sizes, slots, ref).
+
+---
+
+## Local development
+
+Node **22** (matches CI). After `yarn install`:
+
+```bash
+yarn typecheck
+yarn lint
+yarn fmt:check
+yarn test-storybook --run
+yarn build:lib          # ESM/UMD + dist/style.css
+yarn check:pack         # dist artifacts, publint, attw
+yarn check:consumer     # Next 14 smoke against the packed tarball
 ```
 
-## Tech Stack
+`yarn fmt` / `yarn lint:fix` apply formatting and lint fixes. Pre-commit runs `lint-staged` (oxfmt).
+
+---
+
+## Tech stack
 
-- React
-- TypeScript
-- Tailwind CSS
-- class-variance-authority
-- Storybook
-- Vite
+- React 18 + TypeScript
+- Tailwind CSS 3 + class-variance-authority / clsx / tailwind-merge
+- react-aria-components (Button, tabs)
+- @tabler/icons-react
+- Storybook 10 + Vite 7
+- Vitest (browser) + Playwright Chromium
+- oxlint / oxfmt