azamat-ui-kit 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,104 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## Unreleased
+
+## 0.2.0 - 2026-06-19
+
+### Added
+
+- reusable dependency-free chart components: `ChartFrame`, `BarChart`, `LineChart`, `Sparkline`, `DonutChart`, `ChartLegend`, and `MetricTrend`
+- base collapse primitive and composed `CollapseGroup`
+- feedback `Alert` component with info, success, warning, destructive, and muted tones
+- `Statistic`, `StatisticCard`, and `StatisticGrid` display components
+- base UI primitives: `Skeleton`, `SkeletonText`, `SkeletonCard`, `Divider`, `SegmentedControl`, `Spinner`, `LoadingOverlay`, and `Tooltip`
+- Ant-like data display components: `List`, `ListRow`, `Descriptions`, `KanbanBoard`, `TagList`, `TreeView`, `CodeBlock`, `FileCard`, `PropertyGrid`, `DataCard`, and `UserCard`
+- utility display component `KeyboardShortcut`
+- feedback state components `PageState` and `InlineState`
+- action utilities `CopyField` and `ButtonGroup`
+- navigation utility `AnchorNav`
+- interactive `Rating`, `Slider`, `RangeSlider`, `OtpInput`, and `ColorInput` input components
+- reusable dashboard layout helpers: `Section`, `Toolbar`, `SplitLayout`, and `StickyFooterBar`
+- registry status metadata and CLI status output for stable/preview/experimental/internal components
+- README component status, upload example, DataTable pagination note, and troubleshooting sections
+
+### Fixed
+
+- hardened library externals so React, React DOM, JSX runtime and React Hook Form stay external in package builds
+- added build-output smoke checks to catch forbidden ESM `require("react")` usage before release
+- aligned CLI version with the package version
+- aligned `registry.json` version with `package.json`
+- added `.light` theme class output next to `:root` and `.dark`
+- removed `DataTable` search prop type workarounds by typing search through `SearchInputProps`
+- removed the `onValueChange as any` workaround from `DataTable`
+- hardened Calendar keyboard navigation, disabled date reasons, roving tab index, and invalid range handling
+- hardened FileUpload disabled/loading drag-drop behavior and localized rejection messages
+
+### Changed
+
+- build now starts from a clean `dist` directory and runs output validation
+- release gate now includes lint, type/a11y/registry/build-output tests, build, and `npm pack --dry-run`
+- `init` supports Vite and Next.js path defaults through `--template vite|next`
+- registry validation now fails on package/registry version mismatch and duplicate registry dependencies
+- package tarball includes `COMPONENT_MATURITY.md` for public API handoff
+- build-output smoke checks now reject indirect ESM browser require fallbacks such as Rolldown CommonJS helpers and `createRequire`
+- package root exports now include charts, collapse, skeleton, divider, segmented control, spinner, tooltip, rating, sliders, OTP input, color input, list, descriptions, kanban, tree view, code block, file card, property grid, data card, user card and statistic components
+- component maturity docs now define public API decisions, color policy, and font dependency rationale
+
+### Docs
+
+- documented component maturity rubric, public export statuses, helper policy, and audit checklist
+- expanded release handoff with npm 2FA/token, manual consumer smoke, GitHub release notes and docs-app handoff
+
+## 0.1.1 - 2026-06-18
+
+Library-only cleanup release.
+
+### Changed
+
+- version bumped from `0.1.0` to `0.1.1`
+- package exports narrowed to reusable runtime pieces only
+- release documentation updated for the `0.1.1` patch
+
+### Fixed
+
+- removed docs-only `ComponentPreview` from package exports
+- removed unused `prism-react-renderer` runtime dependency
+- silenced expected React Compiler lint noise around TanStack Table integration
+
+## 0.1.0 - 2026-06-18
+
+First public npm-ready release.
+
+### Added
+
+- npm publish metadata: `description`, `keywords`, `homepage`, `repository`, `bugs`, `author`, `license`
+- `LICENSE` file with MIT license
+- dedicated declaration build via `tsconfig.build.json`
+- router-agnostic link rendering through `renderLink` on:
+  - `Breadcrumbs`
+  - `SidebarNav`
+  - `AppSidebar`
+  - `QuickActionGrid`
+- Next.js `renderLink` usage example in `README.md`
+
+### Changed
+
+- version bumped from `0.0.1` to `0.1.0`
+- publish pipeline switched to `prepack`
+- package tarball reduced and cleaned for npm distribution
+- library build no longer copies site/public assets into `dist`
+- exported navigation components no longer require `react-router-dom` at runtime
+
+### Fixed
+
+- `dist/index.d.ts` now generates correctly instead of shipping as an empty file
+- smoke type issues in `tests/smoke/component-imports.test.tsx`
+- a11y smoke compatibility in `src/components/upload/file-upload.tsx`
+
+### Removed
+
+- unused `@radix-ui/*` dependencies
+- unused `vite-plugin-dts`
+- non-library files from published package contents (`src`, docs-site assets, empty templates, extra public artifacts)

package/COMPONENT_MATURITY.md

@@ -0,0 +1,127 @@
+# Component Maturity Matrix
+
+This file is the source of truth for public API readiness in `azamat-ui-kit`. A component can be exported from `src/index.ts` only when its status is explicit.
+
+## Status model
+
+| Status | Meaning | Publish rule |
+| --- | --- | --- |
+| `stable` | API is safe for app use and covered by type/import smoke checks. | Export from package root and registry. |
+| `preview` | Useful and reusable, but API may still change. | Export is allowed with docs caveat. |
+| `experimental` | API is being explored. | Prefer registry-only or internal use until audited. |
+| `internal` | Helper used by other components. | Do not document as a primary component. |
+
+The CLI registry status metadata lives in `cli/registry-status.ts`. `azamat-ui-kit list` displays these statuses so app teams can avoid accidentally treating preview/experimental APIs as stable.
+
+## Maturity rubric
+
+Every public component family is reviewed against these gates:
+
+1. API shape: prop names, controlled/uncontrolled behavior, default values, and escape hatches are clear.
+2. Accessibility: semantic role, aria labels, title/description rules, disabled/read-only behavior, keyboard behavior, and focus return are documented.
+3. Styling: `className` merges last, `data-slot` is present, focus-visible ring uses tokens, and dark mode uses CSS variables.
+4. Runtime safety: no browser globals during SSR unless guarded, no project-specific routing/API imports, and no fake business copy.
+5. Tests/docs: import smoke, render smoke where available, README or handoff example, and registry dependency coverage.
+
+## Public export status
+
+### Stable primitives
+
+| Component | Status | Notes |
+| --- | --- | --- |
+| `Button` | `stable` | Semantic variants: `default`, `secondary`, `outline`, `ghost`, `destructive`, `link`. Loading is handled with disabled state or app-level composition until a dedicated API is added. |
+| `Input` | `stable` | Supports invalid/disabled/read-only styling through native attributes and token classes. Prefix/suffix stays in input wrappers. |
+| `Textarea` | `stable` | Uses token-based border/ring and native resize behavior. |
+| `Checkbox` | `stable` | Indeterminate usage should stay controlled by the consumer. |
+| `Switch` | `stable` | Label/description composition belongs in form or settings-row wrappers. |
+| `Badge` | `stable` | Tone taxonomy should stay token-based and avoid hardcoded project statuses. |
+| `Card` | `stable` | Header/content/footer spacing is the package baseline. Nested cards should be avoided in app docs. |
+| `Tabs` | `stable` | Keep keyboard behavior aligned with the underlying primitive/native pattern. |
+
+### Stable Base UI wrappers
+
+| Component | Status | Notes |
+| --- | --- | --- |
+| `Dialog` | `stable` | Title/description are required by convention for accessible content. Close buttons need an aria label. |
+| `Popover` | `stable` | Placement props should be passed through to the primitive wrapper. |
+| `DropdownMenu` | `stable` | Disabled, destructive and shortcut slots are generic UI concerns. |
+| `Select` | `stable` | Controlled/default value, placeholder, disabled options, group/label/separator remain generic. |
+| `CommandPalette` | `preview` | Only `CommandPalette` and its shortcut hook should be treated as public for now. Low-level command primitives stay internal until composition tests exist. |
+
+### Stable complex families
+
+| Family | Status | Boundary |
+| --- | --- | --- |
+| `actions` | `stable` | Async/loading/destructive behavior must be passed as props; no app API calls. |
+| `layout` | `stable` | Router-agnostic with `renderLink` or regular anchors. |
+| `filters` | `stable` | Controlled filter state belongs to the consumer. |
+| `feedback` | `stable` | Empty/loading/error/success copy is caller-owned. |
+| `display` | `stable` | Metrics/timeline/activity data is caller-owned. |
+| `overlay` | `stable` | Submit/confirm async logic is caller-owned. |
+| `navigation` | `stable` | Pagination is 1-based at the public edge and can be adapted by consumers. |
+
+### Forms and inputs
+
+| Family | Status | Value model |
+| --- | --- | --- |
+| `inputs` | `preview` | Prefer `value` as raw string/number and `onValueChange` or typed callbacks for parsed values. |
+| `form` | `preview` | React Hook Form wrappers should stay type-safe with `Control<FieldValues>` and field-state errors. |
+| `calendar` | `preview` | Values are `YYYY-MM-DD` local-date strings. Consumers own timezone conversion for API payloads. |
+| `upload` | `preview` | Consumers own validation copy; package owns disabled, accept, progress, preview and cleanup behavior. |
+
+### Data and patterns
+
+| Component | Status | Contract |
+| --- | --- | --- |
+| `DataTable` | `preview` | Generic TanStack Table shell. Server/client sorting, filtering and pagination must be explicit in props. Public pagination config uses a 0-based `pageIndex`, matching TanStack Table; visible UI labels may display 1-based page numbers. |
+| `DataTableViewPresets` | `preview` | Persistence is optional and should use caller-provided local/session storage keys. |
+| `ResourcePage` | `preview` | Generic business shell only; no project copy, routes or API assumptions. |
+| `ResourceDetailPage` | `preview` | Sections should remain type-safe and caller-owned. |
+| `FormBuilder` | `experimental` | Remains experimental until custom field render and `FieldPath` type tests exist. |
+
+## Public API decisions
+
+- `ThemeProvider` remains source-only/internal for now. The package-level contract is CSS token ownership in the consumer app, not a root provider export.
+- `InputGroup`/prefix/suffix composition stays internal or wrapper-level until a stable API is designed.
+- Low-level command primitives stay internal; export `CommandPalette` and shortcut helpers only.
+- Root exports stay as-is until a public API snapshot proves that subpath exports are needed for documentation or tree-shaking.
+- Every public API addition/removal must be recorded in `CHANGELOG.md` under Added/Changed/Removed before release.
+
+## Public helper rule
+
+Variant helpers such as `buttonVariants` and `badgeVariants` may stay public when they are documented as styling helpers. If a helper is only used internally, move it out of `src/index.ts` before the next major/minor release.
+
+## Color policy
+
+Token-first classes are required for neutral UI surfaces: `background`, `foreground`, `card`, `popover`, `muted`, `accent`, `border`, `input`, `ring`, `primary`, `secondary`, `destructive`.
+
+Allowed semantic hardcoded palettes are limited to status/tone components and must represent meaning, not layout:
+
+- emerald: success/positive/online
+- amber: warning/pending
+- red: danger/destructive/error when the `destructive` token is not enough for multi-tone status UI
+- blue: info/neutral-progress
+
+Non-semantic neutral palettes such as `zinc`, `slate`, `neutral`, `stone`, `white`, and `black` should be converted to token classes in package components unless they are inside documentation examples or intentionally isolated visual assets.
+
+## Font dependency decision
+
+`@fontsource-variable/geist` stays as a package dependency for now because the CLI theme block imports it into the consumer app CSS. It is not imported by React components directly. If the theme block stops importing the font, the dependency can move out of runtime dependencies.
+
+## Component audit checklist
+
+Use this before promoting any component to `stable`:
+
+- `displayName` where React DevTools value is not obvious.
+- `data-slot` naming matches the package convention.
+- `className` is merged after defaults through `cn(...)`.
+- `ref` forwarding or ref pass-through is intentional.
+- Controlled/uncontrolled props do not conflict.
+- Disabled, read-only and loading semantics are clear.
+- Focus-visible styling uses `ring` tokens.
+- Keyboard behavior is native or documented.
+- Required aria labels, titles and descriptions are documented.
+- Dark mode relies on theme tokens.
+- Responsive overflow behavior is defined.
+- SSR guards exist for `window`, `document`, `localStorage` and object URLs.
+- Tree-shaking is protected by side-effect-free component modules.

package/README.md

@@ -23,16 +23,16 @@ Good candidates:
 
 Do not put project-specific Kassa, LMS, Restaurant, tenant, billing, permission, branch, or API logic into the core UI kit.
 
-## Install
-
-```bash
-npm install azamat-ui-kit
-```
-
-Alternative GitHub install:
-
-```bash
-npm install github:AzamatJurayev-dev/azamat-ui-kit#master
+## Install
+
+```bash
+npm install azamat-ui-kit
+```
+
+Alternative GitHub install:
+
+```bash
+npm install github:AzamatJurayev-dev/azamat-ui-kit#master
 ```
 
 Initialize the project once:
@@ -41,7 +41,19 @@ Initialize the project once:
 npx azamat-ui-kit init
 ```
 
-The package entry does **not** import global CSS. During `init`, the CLI can write Azamat UI Kit theme tokens directly into your app global CSS file, for example `src/index.css`.
+Use Next.js defaults:
+
+```bash
+npx azamat-ui-kit init --template next
+```
+
+Use Vite defaults:
+
+```bash
+npx azamat-ui-kit init --template vite
+```
+
+The package entry does **not** import global CSS. During `init`, the CLI can write Azamat UI Kit theme tokens directly into your app global CSS file, for example `src/index.css` or `app/globals.css`.
 
 Do not import package CSS manually:
 
@@ -50,7 +62,7 @@ Do not import package CSS manually:
 // import "azamat-ui-kit/style.css"
 ```
 
-Use components:
+Use components:
 
 ```tsx
 import {
@@ -80,54 +92,70 @@ import {
   ToastProvider,
   useCommandPaletteShortcut,
   useToast,
-} from "azamat-ui-kit"
-```
-
-## Router integration
-
-The package is router-agnostic by default. Navigation-oriented components render regular `<a>` tags unless you provide a custom link renderer.
-
-Example with Next.js:
-
-```tsx
-import Link from "next/link"
-import { Breadcrumbs, SidebarNav } from "azamat-ui-kit"
-
-<Breadcrumbs
-  items={[
-    { key: "home", label: "Home", href: "/" },
-    { key: "components", label: "Components", href: "/components" },
-  ]}
-  renderLink={({ item, ...props }) => <Link {...props} href={item.href || "#"} />}
-/>
-
-<SidebarNav
-  items={[
-    { key: "dashboard", label: "Dashboard", href: "/dashboard" },
-    { key: "settings", label: "Settings", href: "/settings" },
-  ]}
-  renderLink={({ item, ...props }) => <Link {...props} href={item.href || "#"} />}
-/>
-```
-
-## Local development
-
-```bash
-npm install
-npm run dev
-npm run build
-```
-
-## Release
-
-Useful commands before public release:
-
-```bash
-npm run test:run
-npm pack --dry-run
-```
-
-Release notes live in `CHANGELOG.md`, and the publish flow is documented in `RELEASE.md`.
+} from "azamat-ui-kit"
+```
+
+## Component status
+
+Component readiness is tracked in `COMPONENT_MATURITY.md` and mirrored for the CLI in `cli/registry-status.ts`.
+
+```bash
+npx azamat-ui-kit list
+```
+
+Statuses:
+
+- `stable`: safe public API for app usage.
+- `preview`: reusable, but API may change before a stable release.
+- `experimental`: useful internally, but not ready for stable app contracts.
+- `internal`: helper metadata or implementation detail.
+
+Stable today: primitives, Base UI wrappers, router-agnostic layout/navigation, feedback/display wrappers and generic action/overlay components. Preview today: inputs, forms, calendar, upload, data-table and resource patterns. Experimental today: `FormBuilder` and presets.
+
+## Router integration
+
+The package is router-agnostic by default. Navigation-oriented components render regular `<a>` tags unless you provide a custom link renderer.
+
+Example with Next.js:
+
+```tsx
+import Link from "next/link"
+import { Breadcrumbs, SidebarNav } from "azamat-ui-kit"
+
+<Breadcrumbs
+  items={[
+    { key: "home", label: "Home", href: "/" },
+    { key: "components", label: "Components", href: "/components" },
+  ]}
+  renderLink={({ item, ...props }) => <Link {...props} href={item.href || "#"} />}
+/>
+
+<SidebarNav
+  items={[
+    { key: "dashboard", label: "Dashboard", href: "/dashboard" },
+    { key: "settings", label: "Settings", href: "/settings" },
+  ]}
+  renderLink={({ item, ...props }) => <Link {...props} href={item.href || "#"} />}
+/>
+```
+
+## Local development
+
+```bash
+npm install
+npm run build
+```
+
+## Release
+
+Useful commands before public release:
+
+```bash
+npm run release:gate
+npm pack --dry-run
+```
+
+Release notes live in `CHANGELOG.md`, and the publish flow is documented in `RELEASE.md`.
 
 ## Component rules
 
@@ -165,7 +193,9 @@ Consumer apps own the global CSS. The UI kit only uses token-based classes like
 npx azamat-ui-kit theme src/index.css
 ```
 
-Dark mode works by toggling the `.dark` class on the root/html element.
+Dark mode works by toggling the `.dark` class on the root/html element. The theme block also provides `.light` for explicit light-mode class usage.
+
+The generated theme block imports `@fontsource-variable/geist`; keep that dependency installed when using the CLI theme output.
 
 ## Notifications example
 
@@ -228,6 +258,24 @@ useCommandPaletteShortcut(setOpen)
 <NumberInput value={price} min={0} step={1000} onNumberChange={setPrice} />
 ```
 
+## Upload example
+
+```tsx
+<ImageUpload
+  files={files}
+  onFilesChange={setFiles}
+  maxFiles={4}
+  maxSize={2 * 1024 * 1024}
+  rejectionMessages={{
+    "max-files": ({ maxFiles }) => `Upload at most ${maxFiles} images.`,
+    "max-size": ({ maxSize }) => `Each image must be under ${Math.round((maxSize ?? 0) / 1024 / 1024)} MB.`,
+    type: "Only image files are allowed.",
+  }}
+/>
+```
+
+`ImageUpload` owns object URL preview cleanup when files change, preview is disabled, or the component unmounts. `FileUpload` blocks drag/drop and file dialog interactions while disabled or loading.
+
 ## DataTable example
 
 ```tsx
@@ -281,6 +329,7 @@ function ProductsTable() {
       data={products}
       isLoading={isLoading}
       emptyState={{ title: "No products" }}
+      search={{ value: search, onValueChange: setSearch, placeholder: "Search products" }}
       toolbarProps={(table) => ({
         title: "Products",
         search: <FilterBar search={<SearchInput placeholder="Search" />} />,
@@ -298,26 +347,28 @@ function ProductsTable() {
 }
 ```
 
-## Migration plan
+`DataTable` public pagination config uses a 0-based `pageIndex`, matching TanStack Table. UI copy can display page numbers as 1-based labels.
 
-Phase 1 added low-risk generic wrappers: ModalShell, SheetShell, ConfirmDialog, DialogActions, Pagination, SimpleSelect, MoneyInput, QuantityInput, useSessionStorageState, useBeforeUnloadWhenDirty, useIsMobile.
+## Troubleshooting
 
-Phase 2 added form and async-select layer: AsyncSelect base, FormFieldShell, FormInput, FormSelect, FormAsyncSelect, FormTextarea, FormSwitch, Textarea/Switch exports and react-hook-form peer dependency.
+### Missing theme tokens
 
-Phase 3 improved async select: AsyncMultiSelect, grouped options, quick create, selected option preload, local option cache, selected count labels.
+Run the theme command against the actual global CSS file used by your app. For Vite this is often `src/index.css`; for Next App Router this is often `app/globals.css`.
 
-Phase 4 added data display layer: DataTable, DataTablePagination, DataTableToolbar, EmptyState, LoadingState, StatusBadge.
+```bash
+npx azamat-ui-kit theme app/globals.css
+```
 
-Phase 5 added dashboard helpers: ActionMenu, PageHeader, FilterBar, StatCard, DataTableColumnVisibilityMenu.
+### ESM import issues
 
-Phase 6 added layout/table/input/hook helpers: AppShell, AppHeader, AppSidebar, Checkbox, createDataTableSelectColumn, DataTableSortableHeader, MaskedInput, PhoneInput, useDisclosure, useDebouncedValue, useDebouncedCallback.
+Run `npm run build` in this repo before packing or installing from a local tarball. The build output check rejects ESM browser bundles that contain direct or indirect CommonJS `require` fallbacks.
 
-Phase 7 changed CSS strategy: package entry no longer imports global CSS; `azamat-ui-kit init` writes theme/dark-light tokens into the consumer app global CSS file.
+### Peer dependency mismatch
 
-Phase 8 added advanced inputs and form wrappers: ClearableInput, SearchInput, PasswordInput, NumberInput, DateInput, DateRangeInput, FormSearchInput, FormPasswordInput, FormNumberInput, FormPhoneInput, FormDateInput, FormDateRangeInput.
+Install React and React DOM in the consumer app. They are peer dependencies and are intentionally not bundled into the package runtime.
 
-Phase 9 added data table action helpers: DataTableRowActions, createDataTableActionsColumn, DataTableBulkActions.
+### React Hook Form setup
 
-Phase 10 added notification and command helpers: ToastProvider, useToast, CommandPalette, useCommandPaletteShortcut.
+Form wrappers require `react-hook-form` in the consumer app. Use package imports for reusable wrappers and keep form schema/business validation in the app layer.
 
-Next phase should add calendar / popover date picker and demo playground.
+The library repo only contains reusable package source, CLI helpers, registry templates, tests, and release files. Public docs, blocks, templates showcase pages, and the marketing site live in the separate `azamat-ui` Next.js app.

package/RELEASE.md

@@ -0,0 +1,93 @@
+# Release Checklist
+
+## Before publish
+
+Run the same gate locally from a clean working tree:
+
+```bash
+npm run release:gate
+```
+
+The gate expands to:
+
+```bash
+npm run lint
+npm run test:run
+npm run build
+npm pack --dry-run
+```
+
+Confirm:
+
+- package name is correct: `azamat-ui-kit`
+- version is correct in `package.json`, `registry.json`, and `CHANGELOG.md`
+- `dist/index.js` does not contain runtime `require("react")`
+- `dist/index.cjs` exists for Node/CommonJS consumers
+- `dist/index.d.ts` is not empty and matches the package export map
+- tarball only contains runtime package files, registry manifest, README, changelog, release docs, maturity docs, and license
+- peer dependencies remain external: `react`, `react-dom`, `react/jsx-runtime`, `react-hook-form`
+
+## NPM account and 2FA/token
+
+Use a publish token only from the owner npm account. If the account has 2FA enabled, publish with an OTP from the authenticator app. Do not store the npm token in the repo.
+
+```bash
+npm login
+npm whoami
+npm publish --access public
+```
+
+When publishing from CI later, store the npm token in GitHub Actions secrets and keep package provenance/2FA policy documented in the workflow handoff.
+
+## Manual consumer smoke
+
+After `npm pack --dry-run`, test one clean consumer app before publishing:
+
+```bash
+npm create vite@latest aui-smoke -- --template react-ts
+cd aui-smoke
+npm install ../azamat-ui-kit-0.2.0.tgz
+npx azamat-ui-kit init --template vite
+npx azamat-ui-kit add button input data-table --dry-run
+```
+
+For Next.js:
+
+```bash
+npx create-next-app@latest aui-next-smoke --ts --app
+cd aui-next-smoke
+npm install ../azamat-ui-kit-0.2.0.tgz
+npx azamat-ui-kit init --template next
+```
+
+## After publish
+
+```bash
+npm view azamat-ui-kit version
+```
+
+Recommended follow-up:
+
+- create a GitHub release for the same version
+- copy the matching version notes from `CHANGELOG.md`
+- update the separate docs/showcase app `azamat-ui` to install the published npm version
+- remove any local tarball or workspace workaround from the docs app
+
+## GitHub release notes template
+
+```md
+## Fixes
+- ...
+
+## Changed
+- ...
+
+## Docs
+- ...
+
+## Tests
+- ...
+
+## Known limitations
+- ...
+```