@bizapps/design-system-testing 1.0.7 → 1.0.8

package/README.md

@@ -1,41 +1,74 @@
-# @bizapps/design-system-testing
+# @bizapps/ui — TCCE Design System
 
-A React component library built for TCCE CRM applications. Provides reusable, consistent UI components built with React, TypeScript, and Tailwind CSS v4.
+A React component library built for TCCE CRM applications. Provides reusable, accessible UI components built with React, TypeScript, and Tailwind CSS v4.
+
+> **This is the production package.** For internal testing during development, use [`@bizapps/design-system-testing`](#packages).
 
 ---
 
 ## Table of Contents
 
+- [Packages](#packages)
 - [Requirements](#requirements)
 - [Installation](#installation)
 - [Setup](#setup)
 - [Usage](#usage)
 - [Available Components](#available-components)
+- [Brand Assets](#brand-assets)
 - [Design Tokens](#design-tokens)
-- [Contributing](#contributing)
+- [Local Development](#local-development)
 - [Publishing a New Version](#publishing-a-new-version)
 - [Troubleshooting](#troubleshooting)
 
 ---
 
-## Requirements
+## Packages
 
-Your project must have the following installed before using this library:
+| Package | Purpose | Branch |
+|---|---|---|
+| `@bizapps/ui` | **Production.** Use this in all real projects. | `main` |
+| `@bizapps/design-system-testing` | **Internal testing only.** Never install in real projects. | `develop` |
+
+---
 
-| Package             | Version |
-| ------------------- | ------- |
-| `react`             | ^19     |
-| `react-dom`         | ^19     |
-| `tailwindcss`       | ^4      |
-| `@tailwindcss/vite` | ^4      |
+## Requirements
 
-> **Note:** `shadcn`, `tw-animate-css`, and font packages are already bundled inside the library's CSS. You do **not** need to install them separately.
+Your project must have the following installed:
+
+| Package | Version |
+|---|---|
+| `react` | ^19 |
+| `react-dom` | ^19 |
+| `tailwindcss` | ^4 |
+| `@tailwindcss/vite` | ^4 |
+
+The following peer dependencies are **required** for specific components. Install only what you use:
+
+| Package | Used by |
+|---|---|
+| `lucide-react` | Icon support across components |
+| `radix-ui` | Dialog, Popover, Tooltip, Select, and more |
+| `zod` | Form validation |
+| `react-hook-form` + `@hookform/resolvers` | Form state management |
+| `@tanstack/react-table` | DataTable component |
+| `motion` | Animation tokens |
+| `next-themes` | Theme provider |
+| `sonner` | Toast notifications |
+| `react-day-picker` | Calendar and DatePicker |
+| `embla-carousel-react` | Carousel component |
+| `@schedule-x/*` | EventCalendar component |
+
+> Fonts (`Dax`, `Helvetica Neue`) are served automatically via CDN — no font packages needed.
 
 ---
 
 ## Installation
 
 ```bash
+# Production
+pnpm add @bizapps/ui
+
+# Internal testing only
 pnpm add @bizapps/design-system-testing
 ```
 
@@ -43,7 +76,22 @@ pnpm add @bizapps/design-system-testing
 
 ## Setup
 
-### 1. Configure Vite
+### 1. Wrap your app with `TCCEProvider`
+
+The `TCCEProvider` initializes theming and global context. It must wrap your entire application:
+
+```tsx
+// src/main.tsx
+import { TCCEProvider } from '@bizapps/ui';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <TCCEProvider>
+    <App />
+  </TCCEProvider>
+);
+```
+
+### 2. Configure Vite
 
 Add the Tailwind CSS plugin to your `vite.config.ts`:
 
@@ -53,30 +101,29 @@ import react from '@vitejs/plugin-react';
 import tailwindcss from '@tailwindcss/vite';
 
 export default defineConfig({
-    plugins: [react(), tailwindcss()],
+  plugins: [react(), tailwindcss()],
 });
 ```
 
-### 2. Import the styles
+### 3. Import the styles
 
 In your main CSS file (e.g. `src/index.css`), add these two lines **in this order**:
 
 ```css
 @import 'tailwindcss';
-@import '@bizapps/design-system-testing/styles';
+@import '@bizapps/ui/styles';
 ```
 
 > **Important:** `tailwindcss` must come **before** the library styles so that Tailwind's base layer is available when the library's theme tokens are applied.
 
-### 3. Import the CSS in your entry point
-
-Make sure your `src/main.tsx` imports the CSS file:
+### 4. Import the CSS in your entry point
 
 ```tsx
+// src/main.tsx
 import './index.css';
 ```
 
-That's it. No further configuration is needed.
+That's it. Fonts load automatically from the CDN — no extra configuration needed.
 
 ---
 
@@ -85,14 +132,14 @@ That's it. No further configuration is needed.
 Import components directly from the package:
 
 ```tsx
-import { Button } from '@bizapps/design-system-testing';
+import { Button, Badge, Text } from '@bizapps/ui';
 
 function App() {
-    return (
-        <Button variant='primary' size='md'>
-            Click me
-        </Button>
-    );
+  return (
+    <Button variant="primary" size="md">
+      Click me
+    </Button>
+  );
 }
 ```
 
@@ -100,52 +147,109 @@ function App() {
 
 ## Available Components
 
-### Button
+> 📖 **Full component documentation and interactive examples:**
+> `[Storybook preview — link coming soon]`
+
+### UI Components
+
+| Component | Import |
+|---|---|
+| `Accordion` | `import { Accordion } from '@bizapps/ui'` |
+| `Alert` | `import { Alert } from '@bizapps/ui'` |
+| `AlertDialog` | `import { AlertDialog } from '@bizapps/ui'` |
+| `Avatar` | `import { Avatar } from '@bizapps/ui'` |
+| `Badge` | `import { Badge } from '@bizapps/ui'` |
+| `Breadcrumb` | `import { Breadcrumb } from '@bizapps/ui'` |
+| `Button` | `import { Button } from '@bizapps/ui'` |
+| `Calendar` | `import { Calendar } from '@bizapps/ui'` |
+| `Card` | `import { Card } from '@bizapps/ui'` |
+| `Carousel` | `import { Carousel } from '@bizapps/ui'` |
+| `Checkbox` | `import { Checkbox } from '@bizapps/ui'` |
+| `Combobox` | `import { Combobox } from '@bizapps/ui'` |
+| `Dialog` | `import { Dialog } from '@bizapps/ui'` |
+| `DropdownMenu` | `import { DropdownMenu } from '@bizapps/ui'` |
+| `Dropzone` | `import { Dropzone } from '@bizapps/ui'` |
+| `Empty` | `import { Empty } from '@bizapps/ui'` |
+| `Input` | `import { Input } from '@bizapps/ui'` |
+| `Item` | `import { Item } from '@bizapps/ui'` |
+| `Link` | `import { Link } from '@bizapps/ui'` |
+| `MiniCalendar` | `import { MiniCalendar } from '@bizapps/ui'` |
+| `PinInput` | `import { PinInput } from '@bizapps/ui'` |
+| `Popover` | `import { Popover } from '@bizapps/ui'` |
+| `Progress` | `import { Progress } from '@bizapps/ui'` |
+| `Radio` | `import { RadioGroup } from '@bizapps/ui'` |
+| `Select` | `import { Select } from '@bizapps/ui'` |
+| `Separator` | `import { Separator } from '@bizapps/ui'` |
+| `Skeleton` | `import { Skeleton } from '@bizapps/ui'` |
+| `Slider` | `import { Slider } from '@bizapps/ui'` |
+| `Spinner` | `import { Spinner } from '@bizapps/ui'` |
+| `Status` | `import { Status } from '@bizapps/ui'` |
+| `Switch` | `import { Switch } from '@bizapps/ui'` |
+| `Table` | `import { Table } from '@bizapps/ui'` |
+| `Tabs` | `import { Tabs } from '@bizapps/ui'` |
+| `Text` | `import { Text } from '@bizapps/ui'` |
+| `Toast` | `import { Toast } from '@bizapps/ui'` |
+| `Toggle` | `import { Toggle } from '@bizapps/ui'` |
+| `ToggleGroup` | `import { ToggleGroup } from '@bizapps/ui'` |
+| `Tooltip` | `import { Tooltip } from '@bizapps/ui'` |
+
+### Compound Components
+
+| Component | Import |
+|---|---|
+| `AppShell` | `import { AppShell } from '@bizapps/ui'` |
+| `ColorPicker` | `import { ColorPicker } from '@bizapps/ui'` |
+| `DataTable` | `import { DataTable } from '@bizapps/ui'` |
+| `DatePicker` | `import { DatePicker } from '@bizapps/ui'` |
+| `EventCalendar` | `import { EventCalendar } from '@bizapps/ui'` |
+| `Form` | `import { Form, FormField, FormLabel } from '@bizapps/ui'` |
+| `NavBar` | `import { NavBar } from '@bizapps/ui'` |
+| `Pagination` | `import { Pagination } from '@bizapps/ui'` |
+| `SegmentedControl` | `import { SegmentedControl } from '@bizapps/ui'` |
+| `TextArea` | `import { TextArea } from '@bizapps/ui'` |
+
+### Authorization
+
+| Export | Import |
+|---|---|
+| `Can`, `CanNot` | `import { Can, CanNot } from '@bizapps/ui'` |
+| `AbilityProvider`, `useAbility`, `useCan` | `import { AbilityProvider, useAbility, useCan } from '@bizapps/ui'` |
 
-```tsx
-import { Button } from '@bizapps/design-system-testing';
-```
+---
+
+## Brand Assets
 
-#### Props
+Fonts and logos are served via CloudFront CDN (`https://dibt9vplwriap.cloudfront.net`).
 
-| Prop        | Type                                                           | Default     | Description                               |
-| ----------- | -------------------------------------------------------------- | ----------- | ----------------------------------------- |
-| `variant`   | `'primary' \| 'secondary' \| 'cancel' \| 'outline' \| 'ghost'` | `'primary'` | Visual style of the button                |
-| `size`      | `'sm' \| 'md' \| 'lg' \| 'icon-sm'`                            | `'md'`      | Size of the button                        |
-| `isLoading` | `boolean`                                                      | `false`     | Shows a loading state                     |
-| `disabled`  | `boolean`                                                      | `false`     | Disables the button                       |
-| `asChild`   | `boolean`                                                      | `false`     | Renders as child element (via Radix Slot) |
+**Fonts** load automatically when you import the library styles — no configuration needed.
 
-#### Examples
+**Logos** are available as a typed object:
 
 ```tsx
-// Variants
-<Button variant="primary">Primary</Button>
-<Button variant="secondary">Secondary</Button>
-<Button variant="cancel">Cancel</Button>
-<Button variant="outline">Outline</Button>
-<Button variant="ghost">Ghost</Button>
-
-// Sizes
-<Button size="sm">Small</Button>
-<Button size="md">Medium</Button>
-<Button size="lg">Large</Button>
-
-// States
-<Button disabled>Disabled</Button>
-<Button isLoading>Loading...</Button>
-
-// As a link (using asChild)
-<Button asChild variant="primary">
-  <a href="/dashboard">Go to Dashboard</a>
-</Button>
+import { logos, type LogoKey } from '@bizapps/ui';
+
+// 8 variants: color | colorAna | colorAnaa | negative | positive | grayScale | monochBlack | monochOrange
+<img src={logos.color} alt="TCCE Logo" />
+<img src={logos.negative} alt="TCCE Logo" height={40} />
 ```
 
 ---
 
 ## Design Tokens
 
-The library exposes a full set of CSS custom properties (design tokens) that you can use directly in your project's styles. These are injected globally when you import the library styles.
+All tokens are injected globally when you import the library styles and are also available as Tailwind utility classes.
+
+### Typography
+
+| Font | Weights | Use |
+|---|---|---|
+| `Dax` | 400, 700 | Headings and display text |
+| `Helvetica Neue` | 100–900 (normal + italic) | Body text, UI labels |
+
+```css
+.heading { font-family: 'Dax', Arial, sans-serif; font-weight: 700; }
+.body    { font-family: 'Helvetica Neue', Helvetica, Arial, sans-serif; font-weight: 400; }
+```
 
 ### Colors
 
@@ -157,14 +261,11 @@ The library exposes a full set of CSS custom properties (design tokens) that you
 
 /* Semantic */
 --color-main-positive-state: #01d42f;   /* success */
---color-main-warning-state: #ea3a3d;    /* error/danger */
+--color-main-warning-state: #ea3a3d;    /* error / danger */
 --color-main-yellow-primary: #faca4a;   /* warning */
 
-/* Scales: dark, light, blue, red, orange, yellow, green, purple */
-/* Each scale goes from 100 (lightest) to 1000 (darkest) */
---color-blue-100 through --color-blue-1000
---color-green-100 through --color-green-1000
-/* ...etc */
+/* Scales: blue, green, red, orange, yellow, purple, dark, light */
+/* Each scale: 100 (lightest) → 1000 (darkest) */
 ```
 
 ### Border Radius
@@ -187,41 +288,17 @@ The library exposes a full set of CSS custom properties (design tokens) that you
 --shadow-hover-orange-button
 ```
 
-### Typography
-
-The library includes the following fonts, loaded automatically:
-
-- **Inter Variable** — primary UI font (`--font-sans`)
-- **Dax** — brand heading font
-- **Helvetica Neue** — secondary font
-
-### Using tokens in your CSS
-
-```css
-.my-card {
-    background: var(--color-main-white);
-    border-radius: var(--border-radius-card);
-    box-shadow: var(--shadow-black-card);
-}
-
-.my-card:hover {
-    box-shadow: var(--shadow-hover-black-card);
-}
-```
-
-### Using tokens in Tailwind classes
-
-The tokens are also registered as Tailwind theme values, so you can use them as utility classes:
+### Using tokens in Tailwind
 
 ```tsx
-<div className='bg-main-blue-primary text-main-white rounded-card shadow-black-card'>Hello</div>
+<div className="bg-main-blue-primary text-main-white rounded-card shadow-black-card">
+  Hello
+</div>
 ```
 
 ---
 
-## Contributing
-
-### Local Development
+## Local Development
 
 ```bash
 # Clone the repo
@@ -240,14 +317,7 @@ pnpm dev
 # → http://localhost:5173
 ```
 
-### Adding a New Component
-
-1. Create the component folder under `src/components/ui/ComponentName/`
-2. Build the component following the existing `Button` pattern
-3. Export it from `src/main.ts`
-4. Add a Storybook story under `src/stories/`
-
-### Code Quality
+### Code quality
 
 ```bash
 pnpm lint          # check for lint errors
@@ -256,35 +326,72 @@ pnpm format        # format with Prettier
 pnpm type-check    # TypeScript check without building
 ```
 
+### Adding a new component
+
+1. Run the shadcn CLI first if the component exists in the registry:
+   ```bash
+   pnpm dlx shadcn@latest add <component-name>
+   ```
+2. Adapt the generated file to TCCE design tokens (colors, radius, typography)
+3. Export it from `src/main.ts`
+4. Add a Storybook story under `src/stories/`
+
+> For full contributor guidelines see the [Confluence documentation](https://tcce-tech.atlassian.net/wiki/spaces/DOCAPLSOL/pages/19333122).
+
 ---
 
 ## Publishing a New Version
 
-1. Make your changes and commit them:
+Publishing is **fully automated** via GitHub Actions. Never run `pnpm publish` manually.
 
-```bash
-git add -A
-git commit -m "feat: description of changes"
-```
+### Branch → Package mapping
+
+| Branch | Tag pattern | Publishes |
+|---|---|---|
+| `develop` | `dev-v*` e.g. `dev-v1.0.8` | `@bizapps/design-system-testing` |
+| `main` | `v*` e.g. `v1.0.1` | `@bizapps/ui` |
 
-2. Update the version in `package.json` following [semver](https://semver.org/):
-    - `patch` (0.4.x) → bug fixes
-    - `minor` (0.x.0) → new components or features
-    - `major` (x.0.0) → breaking changes
+> Both branches have **independent** version numbers in `package.json` — they do not need to match.
 
-3. Build the library:
+### Publish a testing version (from `develop`)
 
 ```bash
-pnpm build
+git checkout develop && git pull origin develop
+
+# Bump version in package.json, then:
+git add package.json
+git commit -m "chore: bump version to 1.0.8"
+git push origin develop
+
+git tag -a dev-v1.0.8 -m "Release dev-v1.0.8 - description"
+git push origin dev-v1.0.8
+# → publishes @bizapps/design-system-testing
 ```
 
-4. Publish to npm:
+### Publish a production version (from `main`)
 
 ```bash
-npm publish --access public
+git checkout main && git pull origin main
+
+# Bump version in package.json, then:
+git add package.json
+git commit -m "chore: bump version to 1.0.1"
+git push origin main
+
+git tag -a v1.0.1 -m "Release v1.0.1 - description"
+git push origin v1.0.1
+# → publishes @bizapps/ui
 ```
 
-> Use `npm publish` (not `pnpm publish`) to avoid branch and git-state validation errors from pnpm.
+> ⚠️ `v*` tags created from any branch other than `main` will be **rejected** by the CI.
+
+### Version convention (semver)
+
+| Type | When | Example |
+|---|---|---|
+| `patch` (`x.x.+1`) | Bug fix, style tweak, minor refactor — no API change | `v1.0.0 → v1.0.1` |
+| `minor` (`x.+1.0`) | New component or backwards-compatible feature | `v1.0.1 → v1.1.0` |
+| `major` (`+1.0.0`) | Breaking change requiring updates in consuming apps | `v1.1.0 → v2.0.0` |
 
 ---
 
@@ -295,37 +402,28 @@ npm publish --access public
 Make sure the import order in your CSS file is correct — `tailwindcss` must come first:
 
 ```css
-@import 'tailwindcss'; /* ✅ first */
-@import '@bizapps/design-system-testing/styles'; /* ✅ second */
+@import 'tailwindcss';        /* ✅ first */
+@import '@bizapps/ui/styles'; /* ✅ second */
 ```
 
-### `Cannot resolve './tokens.css'` or similar errors
+### Fonts not loading
 
-This means you're using an older version of the package (0.4.0 or 0.4.1). Update to the latest version:
+Fonts are fetched from the CDN on first render. Make sure the app has internet access and that `dibt9vplwriap.cloudfront.net` is not blocked by a corporate proxy or firewall.
 
-```bash
-pnpm add @bizapps/design-system-testing@latest
-```
+### `v*` tag rejected by CI
 
-### `Scope not found` on publish
-
-The npm scope `@bizapps` belongs to the `bizapps` npm user account. Make sure you're logged in as that user:
+Tags matching `v*` can only be created from commits on `main`. If the workflow fails with `"Tag v* must be created from main"`, merge your changes to `main` first and re-tag from there.
 
-```bash
-npm whoami       # should return: bizapps
-npm login        # if not logged in
-```
+### Version already exists on npm
 
-### pnpm `minimumReleaseAge` policy error
+npm does not allow republishing the same version. Bump to the next version number, commit, and re-tag.
 
-If pnpm blocks installation of a recently published version, run:
+### `Scope not found` on publish
 
-```bash
-pnpm config set minimum-release-age 0 --location project
-```
+The `NPM_TOKEN` secret in the GitHub repo must have publish permissions on the `@bizapps` scope. See the [Confluence deployment docs](https://tcce-tech.atlassian.net/wiki/spaces/DOCAPLSOL/pages/88834079) for token rotation steps.
 
 ---
 
 ## License
 
-MIT — BizAppsTotal &lt;bizapps@tcce.biz&gt;
+MIT — BizAppsTotal <bizapps@tcce.biz>