@mshuja288/aksuicore 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to `@mshuja288/aksuicore` are documented in this file.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [VERSIONING.md](./VERSIONING.md).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-10-05
+
+### Changed
+
+- **Package rename:** `@mshuja288/aksui` → `@mshuja288/aksuicore`
+- Preview control: only the checkbox toggles preview (label/icon no longer toggle); removed bordered preview chrome; checkbox no longer inherits tall field input styles
+- Select menu options: left-aligned with smaller text (`13px`)
+- Avatar menu: larger username, more compact Logout action
+
+### Fixed
+
+- README / docs package name alignment for npm consumers
+
+### Migration
+
+```bash
+npm uninstall @mshuja288/aksui
+npm install @mshuja288/aksuicore@^0.2.0
+```
+
+Update imports from `@mshuja288/aksui` to `@mshuja288/aksuicore` (including `/styles.css`).
+
+## [0.1.0] — 2026-10-04
+
+### Added
+
+- Theme tokens (`--aks-*`) with configurator compatibility aliases
+- Primitives: `Button`, `Select`, `DateField`, `Dialog`, `Snackbar`, `Topbar`, `SideNav`, `Pagination`, `FormActions`
+- Patterns: `RecordWorkspace` (table + side rail + preview + filters), `AppShell` (topbar + side nav + mobile bottom nav)
+- Deprecated migration aliases: `AppSelect`, `FormDialog`, `StatusMessage`, `RecordTable`
+- Vite playground for visual demos
+
+Published originally as `@mshuja288/aksui@0.1.0`.
+
+[Unreleased]: https://github.com/mshuja288/aksui/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/mshuja288/aksui/releases/tag/v0.2.0
+[0.1.0]: https://github.com/mshuja288/aksui/releases/tag/v0.1.0

package/PLAN.md

@@ -0,0 +1,139 @@
+# aksui Implementation Plan
+
+Track progress here. Mark items `[x]` when done.
+
+Library: `@mshuja288/aksuicore`  
+First consumer: `aksconfigurator_ui`  
+Principle: library owns presentation + interaction patterns; apps own APIs and domain forms.
+
+---
+
+## Phase 0 — Scaffold
+
+- [x] Create `E:\ikssam\aksui` repository
+- [x] Library package boilerplate (`package.json`, TypeScript, tsup)
+- [x] Theme token stub (`src/theme/aksui.css`)
+- [x] Folder layout: `primitives/`, `patterns/`, `theme/`
+- [x] Playground Vite app shell with dummy placeholder page
+- [x] This plan document
+
+---
+
+## Phase 1 — Foundation
+
+Goal: installable package + stable theme contract.
+
+- [x] Install root + playground dependencies (`npm run setup`)
+- [x] Verify `npm run build` produces `dist/` + `aksui.css`
+- [x] Verify playground runs (`npm run playground`)
+- [x] Align CSS tokens with current configurator brand values
+- [x] Document local consumption (`file:` / workspace link)
+- [x] Decide private npm registry target → **GitHub Packages** for `@ikssam` (local `file:` until Phase 6)
+
+---
+
+## Phase 2 — Primitives
+
+Extract low-level reusable components from `aksconfigurator_ui`.
+
+Order of extraction:
+
+1. [x] Button / Ghost / Danger variants
+2. [x] AppSelect + LookupSelect patterns (generic Select first; LookupSelect stays in apps)
+3. [x] DateField
+4. [x] Dialog / FormDialog shell
+5. [x] Snackbar / StatusMessage
+6. [x] Topbar (brand + avatar menu slot)
+7. [x] SideNav (app shell left menu)
+8. [x] Pagination controls
+
+For each primitive:
+
+- [x] Move/adapt component into `src/primitives`
+- [x] Export from package entry
+- [x] Add playground demo with dummy props
+- [x] Keep domain lookups (status/enabled options) in apps, not aksui
+
+---
+
+## Phase 3 — Record Workspace template (flagship)
+
+This is the manager’s reusable template:
+
+**Table + right collapsible rail** including:
+
+- [x] Data table with column model
+- [x] Per-record actions (View / Update / Delete as callbacks/slots)
+- [x] Sorting
+- [x] Client filters + Reset
+- [x] Preview mode checkbox + preview panel
+- [x] Hover tooltip (when preview off)
+- [x] Add action in rail
+- [x] Pagination
+- [x] Dialog host slot for Add/Update/View forms (form body stays in app)
+
+Deliverable:
+
+- [x] `RecordWorkspace<T>` (or equivalent) in `src/patterns`
+- [x] Full playground demo with dummy companies/modules data
+- [x] Typed public API documented in README
+
+---
+
+## Phase 4 — App shell template (optional but useful)
+
+- [x] `AppShell` composing Topbar + SideNav + content area
+- [x] Playground demo of full app chrome with dummy nav items
+
+---
+
+## Phase 5 — Consume from aksconfigurator_ui
+
+- [x] Link `@mshuja288/aksuicore` into configurator UI
+- [x] Replace local theme tokens with aksui styles
+- [x] Replace RecordTable usage with RecordWorkspace
+- [x] Replace shared primitives gradually
+- [x] Remove duplicated local UI once parity confirmed
+- [ ] Regression pass: Companies, Modules, Licenses, Parameters, Audit
+
+---
+
+## Phase 6 — Versioning & publish
+
+- [x] Semver policy (0.x while stabilizing; 1.0 when template API is stable) → `VERSIONING.md`
+- [x] CHANGELOG.md (`0.1.0`)
+- [x] `npm pack` / publish dry-run (`npm run pack:check`)
+- [x] CI: typecheck + build (+ playground build) → `.github/workflows/ci.yml` + `npm run ci`
+- [ ] Tag `v0.1.0` after first git commit + push (repo currently has no commits)
+
+---
+
+## Phase 7 — Ready for next module UIs
+
+- [ ] Short “How to build a screen with aksui” guide
+- [ ] Starter checklist for new apps (install, import styles, AppShell, RecordWorkspace)
+- [ ] Freeze breaking changes behind minor/major bumps
+
+---
+
+## Progress log
+
+| Date | Note |
+|------|------|
+| 2026-10-04 | Boilerplate created; plan drafted |
+| 2026-10-04 | Phase 1 done: tokens aligned, playground verified, local + GitHub Packages docs |
+| 2026-10-04 | Phase 2 done: Button, Select, DateField, Dialog, Snackbar, Topbar, SideNav, Pagination + playground |
+| 2026-10-04 | Phase 3 done: RecordWorkspace template + dummy companies playground demo |
+| 2026-10-04 | Phase 4 done: AppShell pattern; playground uses AppShell chrome |
+| 2026-10-04 | Phase 5: aksconfigurator_ui consumes aksui (AppShell, RecordWorkspace, primitives); local duplicates removed |
+| 2026-10-04 | Phase 6: VERSIONING + CHANGELOG + CI workflow + pack dry-run; tag pending first commit |
+
+---
+
+## Out of scope (for now)
+
+- Domain API clients
+- Auth / JWT handling
+- Business validation rules
+- Parameters/Audit-specific form logic
+- Forced Tailwind adoption

package/README.md

@@ -0,0 +1,192 @@
+# @mshuja288/aksuicore
+
+Shared React UI library for Ikssam apps — reusable **primitives** and **templates** (especially the Record Workspace).
+
+## Status
+
+`v0.2.0` — package renamed to `@mshuja288/aksuicore`. Published on npmjs. See [CHANGELOG.md](./CHANGELOG.md).
+
+## AppShell API
+
+```tsx
+import { AppShell, RecordWorkspace } from "@mshuja288/aksuicore";
+
+<AppShell
+  title="Configurator"
+  username="admin"
+  onLogout={signOut}
+  navItems={[
+    { id: "companies", label: "Companies" },
+    { id: "modules", label: "Modules" },
+  ]}
+  activeNavId={screen}
+  onNavSelect={setScreen}
+>
+  <RecordWorkspace ... />
+</AppShell>
+```
+
+
+## RecordWorkspace API
+
+```tsx
+import "@mshuja288/aksuicore/styles.css";
+import { RecordWorkspace, Dialog, type TableColumn } from "@mshuja288/aksuicore";
+
+type Row = { id: number; name: string; status: string };
+
+const columns: TableColumn<Row>[] = [
+  { key: "id", header: "ID", value: (r) => r.id },
+  { key: "name", header: "Name", value: (r) => r.name },
+  {
+    key: "status",
+    header: "Status",
+    value: (r) => r.status,
+    filterOptions: [
+      { value: "DFT", label: "Draft" },
+      { value: "APP", label: "Approved" },
+    ],
+    filterPlaceholder: "All statuses",
+  },
+];
+
+<RecordWorkspace
+  title="Companies"
+  empty="No records yet."
+  columns={columns}
+  items={rows}
+  rowKey={(r) => r.id}
+  addLabel="Add company"
+  onAdd={openCreate}
+  onView={openView}
+  onUpdate={openUpdate}
+  onDelete={removeRow}
+  toolbar={/* optional company picker etc */}
+  form={/* <Dialog>...</Dialog> owned by the app */}
+/>
+```
+
+Domain lookups stay in the app via `filterOptions`. Form bodies stay in the `form` slot.
+
+See **[PLAN.md](./PLAN.md)** for the phased roadmap and progress checklist.
+
+## Structure
+
+```
+aksui/
+  src/
+    theme/         Design tokens + base stylesheet
+    primitives/    Buttons, nav, dialogs, inputs, pagination
+    patterns/      RecordWorkspace and other templates
+  playground/      Visual demo app with dummy data
+  dist/            Built package output
+  PLAN.md          Step-by-step implementation tracker
+```
+
+## Setup
+
+```bash
+# from E:\ikssam\aksui
+npm run setup          # installs root + playground deps
+npm run build          # emits dist/ + dist/aksui.css
+npm run typecheck
+npm run playground     # http://localhost:5173
+npm run pack:check     # dry-run of npm pack contents
+```
+
+## Theme
+
+Import once in the host app:
+
+```tsx
+import "@mshuja288/aksuicore/styles.css";
+```
+
+Canonical tokens use the `--aks-*` prefix. Compatibility aliases (`--brand`, `--accent`, …) are also defined so existing configurator CSS can migrate gradually.
+
+TypeScript mirror: `aksuiTokens` / `aksuiThemeVersion`.
+
+## Local consumption (recommended while developing)
+
+From an app next to this repo (e.g. `aksconfigurator_ui`):
+
+1. Build the library: `npm run build` in `aksui`
+2. In the app `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@mshuja288/aksuicore": "file:../aksui"
+  }
+}
+```
+
+3. Install in the app: `npm install`
+4. Import styles + components:
+
+```tsx
+import "@mshuja288/aksuicore/styles.css";
+import { aksuiThemeVersion } from "@mshuja288/aksuicore";
+```
+
+5. **Next.js (Turbopack) apps** — set `turbopack.root` to the monorepo parent and alias the package to source (Windows absolute paths are not supported yet):
+
+```ts
+// next.config.ts
+turbopack: {
+  root: path.resolve(__dirname, ".."),
+  resolveAlias: {
+    "@mshuja288/aksuicore": "./aksui/src/index.ts",
+    "@mshuja288/aksuicore/styles.css": "./aksui/dist/aksui.css",
+  },
+},
+transpilePackages: ["@mshuja288/aksuicore"],
+```
+
+Re-run `npm run build` in `aksui` after library CSS/API changes (or use playground, which aliases `src` directly).
+
+### Alternative: npm link
+
+```bash
+# in aksui
+npm run build
+npm link
+
+# in aksconfigurator_ui
+npm link @mshuja288/aksuicore
+```
+
+Prefer `file:../aksui` for simpler team workflows on Windows.
+
+## Versioning & publish
+
+- Semver rules: [VERSIONING.md](./VERSIONING.md)
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)
+- CI: `.github/workflows/ci.yml` (typecheck, build, pack dry-run, playground build)
+- Local verify: `npm run ci`
+
+### GitHub Packages
+
+| Stage | Approach |
+|-------|----------|
+| **Development** | `file:../aksui` (or `npm link`) |
+| **Publish** | GitHub Packages — `@ikssam` scope |
+
+```bash
+# once: auth (PAT with write:packages)
+cp .npmrc.example .npmrc   # or merge into ~/.npmrc
+# set NODE_AUTH_TOKEN
+
+npm run ci
+npm publish
+```
+
+Note: GitHub Packages usually requires the package scope (`@ikssam`) to match a GitHub org of the same name. If the repo lives under a personal account, either create/transfer to an `ikssam` org or rename the package scope before the first publish.
+
+Example auth config: [`.npmrc.example`](./.npmrc.example).
+
+## Design rules
+
+- Library owns look, chrome, and interaction patterns
+- Apps own APIs, auth, and domain form bodies
+- React / ReactDOM are peer dependencies

package/VERSIONING.md

@@ -0,0 +1,33 @@
+# Versioning policy — `@mshuja288/aksuicore`
+
+## Semver
+
+| Range | Meaning |
+|-------|---------|
+| **0.x** | Stabilizing. Breaking changes allowed in minor bumps (`0.2.0`) when called out in CHANGELOG. |
+| **1.0.0** | Template API is stable (`AppShell`, `RecordWorkspace`, core primitives). Breaking changes require a major bump. |
+| **Patch** (`0.1.x`) | Bug fixes, style tweaks, docs — no intentional API breaks. |
+| **Minor** (`0.x.0` while `< 1.0`) | New components/props, or intentional breaking changes during 0.x. |
+| **Major** (`≥ 1.0`) | Breaking public API or CSS contract changes. |
+
+## Public API surface
+
+Breaking if removed/renamed/behavior-changed without a major (or 0.x minor) bump:
+
+- Named exports from `@mshuja288/aksuicore`
+- `@mshuja288/aksuicore/styles.css` and `--aks-*` tokens (compatibility aliases `--name` may be removed only in a major)
+- Prop contracts for `AppShell`, `RecordWorkspace`, and primitives listed in README
+
+Deprecated aliases (`FormDialog`, `StatusMessage`, `AppSelect`, `RecordTable`) may be removed in a future **1.0** or a documented 0.x minor.
+
+## Release checklist
+
+1. Update `CHANGELOG.md` under `[Unreleased]` → version section
+2. Bump `version` in `package.json` (and `aksuiThemeVersion` if you treat it as the package version)
+3. `npm run typecheck && npm run build && npm run playground:build && npm run pack:check`
+4. Commit, tag `vX.Y.Z`, push tag
+5. Publish to GitHub Packages (see README)
+
+## Tags
+
+Git tags use the `v` prefix matching `package.json` version (e.g. `v0.1.0`).