diff --git a/.github/workflows/cd-release.yml b/.github/workflows/cd-release.yml index 3141924..09d2ba7 100644 --- a/.github/workflows/cd-release.yml +++ b/.github/workflows/cd-release.yml @@ -21,8 +21,8 @@ jobs: - name: Setup Node.js uses: actions/setup-node@v4 with: - node-version: "20" - registry-url: "https://registry.npmjs.org" + node-version: '20' + registry-url: 'https://registry.npmjs.org' - name: Install dependencies run: npm ci diff --git a/.github/workflows/ci-pr-validation.yml b/.github/workflows/ci-pr-validation.yml index a2b018a..a5d6243 100644 --- a/.github/workflows/ci-pr-validation.yml +++ b/.github/workflows/ci-pr-validation.yml @@ -2,9 +2,7 @@ name: CI - PR Validation on: pull_request: - branches: [develop] - push: - branches: [develop] + branches: [master] permissions: contents: read diff --git a/.github/workflows/ci-release-check.yml b/.github/workflows/ci-release-check.yml index a49ce6b..2b3fefd 100644 --- a/.github/workflows/ci-release-check.yml +++ b/.github/workflows/ci-release-check.yml @@ -13,8 +13,6 @@ env: jobs: release-check: name: CI - Release Check - # Only run when PR is from develop -> master - if: github.head_ref == 'develop' runs-on: ubuntu-latest steps: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..3ae5343 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,45 @@ +name: CI +on: + push: + branches: [develop, master] + pull_request: + branches: [master] + +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'npm' + - run: npm ci + - run: npm run lint + - run: npm run typecheck + - run: npm run test:cov + + build: + runs-on: ubuntu-latest + needs: test + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'npm' + - run: npm ci + - run: npm run build + + e2e: + runs-on: ubuntu-latest + needs: test + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'npm' + - run: npm ci + - run: npx playwright install --with-deps + - run: npm run e2e diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..4724440 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,33 @@ +name: Release +on: + push: + branches: [master] + +permissions: + contents: write + pull-requests: write + id-token: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: 'npm' + - run: npm ci + - run: npm run lint + - run: npm run typecheck + - run: npm test + - run: npm run build + - name: Changesets Release + uses: changesets/action@v1 + with: + publish: npm publish --provenance + title: 'Release: version packages' + commit: 'chore: version packages' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.husky/_/.gitignore b/.husky/_/.gitignore index 234d3f7..f59ec20 100644 --- a/.husky/_/.gitignore +++ b/.husky/_/.gitignore @@ -1 +1 @@ -# * \ No newline at end of file +* \ No newline at end of file diff --git a/.husky/pre-commit b/.husky/pre-commit index d24fdfc..46d500c 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,4 +1,4 @@ -#!/usr/bin/env sh -. "$(dirname -- "$0")/_/husky.sh" - -npx lint-staged +npm run format:write +npm run lint +npm run typecheck +npm test diff --git a/.husky/pre-push b/.husky/pre-push index acfd8a0..8ddb6b0 100755 --- a/.husky/pre-push +++ b/.husky/pre-push @@ -1,5 +1,2 @@ -#!/usr/bin/env sh -. "$(dirname -- "$0")/_/husky.sh" - npm run typecheck npm test diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..ef2237c --- /dev/null +++ b/.prettierrc @@ -0,0 +1,8 @@ +{ + "semi": true, + "singleQuote": true, + "trailingComma": "all", + "printWidth": 100, + "tabWidth": 2, + "endOfLine": "lf" +} diff --git a/README.md b/README.md index 539fe85..d0c7fca 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,20 @@ Template repository for building reusable React TypeScript **npm libraries** - Dependency-free styling (Tailwind-compatible by convention only) - `react` and `react-dom` as peerDependencies +## Peer Dependencies & Requirements + +- React ecosystem: + - `react` and `react-dom` (host-provided) + - `react-router-dom` (required if you use `Breadcrumb` or any router-integrated components) + - `zod` (required if you use `ControlledZodDynamicForm`) + - `@ciscode/ui-translate-core` (optional i18n provider used by some components) + +Install in host app: + +```bash +npm i react react-dom react-router-dom zod @ciscode/ui-translate-core +``` + ## Package structure - `src/components` – reusable UI components @@ -25,12 +39,127 @@ Anything not exported from `src/index.ts` is considered private. ## Scripts -- `npm run build` – build to `dist/` (tsup) -- `npm test` – run tests (vitest) +## Scripts + +- `npm run dev` – start Vite dev server (for docs/examples) +- `npm run preview` – preview Vite build +- `npm run build` – build library to `dist/` (tsup: ESM + CJS + dts) +- `npm test` – run unit/integration tests (Vitest) +- `npm run test:cov` – run tests with coverage report +- `npm run e2e` / `npm run e2e:headed` – run Playwright tests - `npm run typecheck` – TypeScript typecheck +- `npm run type-check:watch` – TypeScript typecheck in watch mode - `npm run lint` – ESLint - `npm run format` / `npm run format:write` – Prettier - `npx changeset` – create a changeset + Anything not exported from `src/index.ts` is considered private. + +### Public API (summary) + +Root exports from `src/index.ts`: + +- Components: `Template`, `Breadcrumb`, `ControlledZodDynamicForm`, `TableDataCustom` +- Hooks: `useLocalStorage`, `useColorMode`, `generatePageNumbers` +- Types: `ColumnConfigTable`, `FieldConfigDynamicForm`, `ToolbarItem`, `SidebarItem`, `SidebarSection`, and layout types (`TemplateSidebarConfig`, `TemplateNavbarConfig`, `TemplateFooterConfig`, etc.) + +Internal-only components and utilities are intentionally not exported to avoid coupling (e.g. base-only table components). Use the wrapped components provided by the public API. + +### Router Integration + +Some components (e.g., `Breadcrumb`) rely on React Router. In host apps, wrap your app with `RouterProvider` from `react-router-dom` and ensure `Link` works: + +```tsx +import { createBrowserRouter, RouterProvider } from 'react-router-dom'; +const router = createBrowserRouter([{ path: '/', element: }]); +export function Root() { + return ; +} +``` + +### Usage Examples + +Hooks + +- `useLocalStorage`: + ```tsx + const [theme, setTheme] = useLocalStorage('color-theme', 'light'); + ``` +- `useLogin`: + ```tsx + const { values, update, submit, loading, error } = useLogin({ + login: async ({ username, password }) => ({ user: { name: username }, token: 't123' }), + schema: { parse: (v) => v }, + }); + ``` + +Components + +- `Breadcrumb`: + + ```tsx + + ``` + +- `TableDataCustom`: + + ```tsx + import { TableDataCustom, type ColumnConfigTable } from '@ciscode/template-fe'; + + type Row = { id: number; name: string }; + const columns: ColumnConfigTable[] = [ + { key: 'id', title: 'ID' }, + { key: 'name', title: 'Name' }, + ]; + + + columns={columns} + data={[{ id: 1, name: 'Alice' }]} + pagination={{ + currentPage: 1, + totalPages: 3, + totalItems: 1, + onPageChange: (p) => console.log(p), + }} + />; + ``` + +- `ControlledZodDynamicForm`: + + ```tsx + import { ControlledZodDynamicForm, type FieldConfigDynamicForm } from '@ciscode/template-fe'; + import { z } from 'zod'; + + const schema = z.object({ name: z.string().min(1) }); + const fields: FieldConfigDynamicForm[] = [{ key: 'name', label: 'Name', type: 'text' }]; + + { + /* update your form state */ + }} + onSubmit={(values) => console.log(values)} + />; + ``` + +### Migration Guide (from older template) + +- Router: switch imports to `react-router-dom` (`Link`, `RouterProvider`). +- Forms: `ControlledZodDynamicForm` expects controlled `values` and `onChangeField` for reliability. +- Table: use `TableDataCustom` wrapper; base-only internals are private. +- Exports: import only from the package root — all public APIs are re-exported via `src/index.ts`. + +### Testing & Coverage + +- Unit tests live under `tests/unit/` and run in `jsdom`. +- Coverage uses `v8` provider; HTML report is written to `coverage/`. +- We exclude demo/layout code from coverage to focus on exported library APIs. + +### RTL Support + +- Pagination icons respond to `document.dir` and mirror correctly for RTL. +- Components use `ltr:` / `rtl:` Tailwind variants where layout matters. ## Release flow (summary) @@ -40,5 +169,29 @@ Anything not exported from `src/index.ts` is considered private. - Promote `develop` → `master` - Tag `vX.Y.Z` to publish (npm OIDC) +### Examples App + +- Run the local examples to preview components: + +```bash +npm run dev:examples +``` + +- The examples import from the local source via an alias `@ciscode/template-fe`. + +To publish: + +- Ensure `npm run prepublishOnly` passes (format, lint, typecheck, tests, build). +- Use Changesets to bump versions and generate changelog. +- Publish with `npm publish --provenance`. + +### Publishing Checklist + +- `npm run prepublishOnly` succeeds +- Unit coverage ≥ 80% +- E2E smoke/examples pass (optional for host-only packages) +- Changeset created and PR merged +- `dist/` contains `index.js`, `index.cjs`, `index.d.ts` + This repository is a **template**. Teams should clone it and focus only on library logic, not tooling or release mechanics. diff --git a/dist/index.d.ts b/dist/index.d.ts index 8976096..25c3bb6 100644 --- a/dist/index.d.ts +++ b/dist/index.d.ts @@ -1,3 +1,391 @@ -import './assets/styles/style.css'; -export * from './main/app'; -//# sourceMappingURL=index.d.ts.map \ No newline at end of file +import * as React$1 from 'react'; +import React__default, { ReactNode } from 'react'; +import * as react_jsx_runtime from 'react/jsx-runtime'; +import { ZodSchema } from 'zod'; + +/** Each item within a section */ +interface SidebarItem$1 { + label: string; + path?: string; + icon?: JSX.Element; + order?: number; + children?: SidebarItem$1[]; +} +/** Each section has a name, an optional order, and an array of items */ +interface SidebarSection { + name: string; + order?: number; + items: SidebarItem$1[]; +} + +type VisibilityRule = { + /** Visible if user has at least one of these roles */ + roles?: string[]; + /** Visible if user has every permission listed here */ + permissions?: string[]; + /** Visible if user has at least one of these modules */ + modules?: string[]; +}; +type SidebarBase = { + id: string; + label: string; + /** Iconify icon name string (e.g., "mdi:view-dashboard") */ + icon?: string; + /** Nested menus (collapsible groups) */ + children?: SidebarItem[]; + /** If omitted, item is visible. If provided, item is hidden unless rule passes. */ + visibility?: VisibilityRule; +}; +type SidebarInternalLink = SidebarBase & { + to: string; + href?: never; + action?: never; +}; +type SidebarExternalLink = SidebarBase & { + href: string; + to?: never; + action?: never; + newTab?: boolean; +}; +type SidebarActionItem = SidebarBase & { + action: 'logout' | (string & {}); + to?: never; + href?: never; +}; +type SidebarItem = SidebarInternalLink | SidebarExternalLink | SidebarActionItem; +type TemplateSidebarConfig = { + items: SidebarItem[]; + className?: string; +}; +type TemplateNavbarBrandConfig = { + title?: string; + href?: string; + logoSrc?: string; + logoAlt?: string; +}; +type TemplateNavbarConfig = { + brand?: TemplateNavbarBrandConfig; + /** Optional full override */ + brandSlot?: ReactNode; + className?: string; +}; +type TemplateFooterLink = { + label: string; + href: string; + /** + * If omitted, default behavior is new tab (true). + * Can be overridden per link. + */ + newTab?: boolean; +}; +type TemplateFooterPresetConfig = { + leftText: string; + links?: TemplateFooterLink[]; + version?: string; +}; +type TemplateFooterConfig = { + /** + * Advanced: fully custom footer blocks (you control JSX). + * Optional because preset-only is valid. + */ + blocks?: ReactNode[]; + /** + * Preset: data-driven styled footer rendered by the template. + */ + preset?: TemplateFooterPresetConfig; + /** + * Optional className override on the footer wrapper. + */ + className?: string; +}; +type TemplateLayoutConfig = { + sidebar?: TemplateSidebarConfig; + navbar?: TemplateNavbarConfig; + footer?: TemplateFooterConfig; +}; + +/** + * Props for the `Template` (Dashboard Shell) component. + * Backward compatible with legacy sidebar/logo/onLogout while + * supporting modern `sidebar`, `navbar`, and optional `footer` configs. + */ +interface DashboardProps { + children: ReactNode; + /** + * Legacy props (backward compatible) + */ + sidebarContent?: SidebarSection[]; + logo?: ReactNode; + onLogout?: () => void; + /** + * New config props (preferred) + */ + sidebar?: TemplateSidebarConfig; + navbar?: TemplateNavbarConfig; + /** + * Optional footer (rendered inside DashboardLayout when provided) + */ + footer?: TemplateFooterConfig; +} +/** + * Template (Dashboard Shell) + * + * Backward compatible: + * - Existing apps can keep using: sidebarContent + logo + onLogout + * Preferred: + * - New apps should use: sidebar + navbar (+ footer when needed) + */ +declare const Template: React__default.FC; + +/** + * Props for `Breadcrumb` component. + * - `pageName`: current page label displayed in the trail. + */ +interface BreadcrumbProps { + pageName: string; +} +/** + * Accessible breadcrumb navigation. + * Renders a current page label and a link to home. + */ +declare const Breadcrumb: React__default.FC; + +/** The list of supported field types. */ +type FieldType = 'text' | 'number' | 'textarea' | 'select' | 'checkbox' | 'multiSelect' | 'custom'; +/** For select-type fields, each option has a label and a value. */ +interface FieldOption { + label: string; + value: string | number; +} +/** + * Describes each field in your dynamic form: + * - name, label, type, (optionally) placeholder, options, etc. + * - if "type" is "custom", you can supply a "component" + * that the form will render directly. + */ +interface FieldConfigDynamicForm { + /** Unique field name => used to store the value in state, reference in Zod schema, etc. */ + name: string; + /** The label displayed above or next to the input. */ + label?: string; + /** Type of input: text, number, textarea, select, checkbox, multiSelect, or custom. */ + type: FieldType; + /** Optional placeholder text for text/textarea/number fields. */ + placeholder?: string; + /** For select or multiSelect, an array of label/value pairs. */ + options?: FieldOption[]; + /** Default initial value (e.g. '', 0, [], etc.). */ + defaultValue?: any; + /** For multiSelect or custom logic, an optional URL for searching. */ + /** + * If `type` is 'custom', you can specify a React component + * that the form will render. This component should accept + * props like { value: any, onChange: (val: any) => void } at minimum. + */ + component?: React__default.ComponentType; + step?: string; + /** + * Tailwind classes for the field wrapper (the
). + * e.g. "w-1/2 px-2" or "col-span-2" or "flex-1" + */ + wrapperClassName?: string; + /** + * If you want custom classes for the