dst-rg 1.0.0

package/.gitlab-ci.yml

@@ -0,0 +1,43 @@
+# This file is a template, and might need editing before it works on your project.
+# This is a sample GitLab CI/CD configuration file that should run without any modifications.
+# It demonstrates a basic 3 stage CI/CD pipeline. Instead of real tests or scripts,
+# it uses echo commands to simulate the pipeline execution.
+#
+# A pipeline is composed of independent jobs that run scripts, grouped into stages.
+# Stages run in sequential order, but jobs within stages run in parallel.
+#
+# For more information, see: https://docs.gitlab.com/ee/ci/yaml/#stages
+#
+# You can copy and paste this template into a new `.gitlab-ci.yml` file.
+# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.
+#
+# To contribute improvements to CI/CD templates, please follow the Development guide at:
+# https://docs.gitlab.com/development/cicd/templates/
+# This specific template is located at:
+# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Getting-Started.gitlab-ci.yml
+
+stages:          # List of stages for jobs, and their order of execution
+  - test
+  - deploy
+
+
+unit-test-job:   # This job runs in the test stage.
+  stage: test    # It only starts when the job in the build stage completes successfully.
+  script:
+    - echo "Running unit tests... This will take about 60 seconds."
+    - pnpm install && pnpm test && pnpm build
+
+
+deploy-job:      # This job runs in the deploy stage.
+  stage: deploy  # It only runs when *both* jobs in the test stage complete successfully.
+  environment: production
+  script:
+    - echo "Deploying application..."
+    - echo $SSH_USER
+    - echo $SERVER_HOST
+    - echo $DEPLOY_PATH
+    - whoami
+    - ssh $SSH_USER@$SERVER_HOST "cd $DEPLOY_PATH && git pull && pnpm install   && pm2 restart all"
+    - echo "Application successfully deployed."
+  only:
+     - main

package/.storybook/main.ts

@@ -0,0 +1,15 @@
+import type { StorybookConfig } from "@storybook/react-vite";
+
+const config: StorybookConfig = {
+  stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
+  addons: [
+    "@storybook/addon-onboarding",
+    "@chromatic-com/storybook",
+    "@storybook/addon-docs"
+  ],
+  framework: {
+    name: "@storybook/react-vite",
+    options: {},
+  },
+};
+export default config;

package/.storybook/preview.ts

@@ -0,0 +1,15 @@
+import "../src/index.css";
+import type { Preview } from "@storybook/react-vite";
+
+const preview: Preview = {
+  parameters: {
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/i,
+      },
+    },
+  },
+};
+
+export default preview;

package/README.md

@@ -0,0 +1,254 @@
+# RG Design System Template – Developer Guide
+
+A scalable, reusable React + TypeScript component library with Vite, Tailwind CSS, Storybook, ESLint, and Vitest. This README helps new contributors understand the structure, conventions, and workflows to confidently add or update code and resolve issues.
+
+## Stack
+- React 19, TypeScript 5, Vite 6
+- Tailwind CSS 4 (with `@tailwindcss/vite`); PostCSS for CSS build
+- Storybook 8 (React + Vite)
+- Vitest 3 + Testing Library + JSDOM
+- ESLint 9 (typescript-eslint, react-hooks, react-refresh)
+- Rollup for library bundling (ESM + CJS + DTS)
+
+## Project Structure
+
+```
+.
+├─ src/
+│  ├─ assets/
+│  │  └─ style/                 # Base CSS tokens and utilities (compiled into dist/style.css)
+│  ├─ components/
+│  │  ├─ <ComponentName>/       # One folder per public component
+│  │  │  ├─ index.tsx           # Component implementation (export default/named)
+│  │  │  ├─ _.style.ts          # Styles (e.g., cva, class composition)
+│  │  │  ├─ _.types.ts|type.ts  # Component props/types
+│  │  │  ├─ _.stories.tsx       # Storybook stories
+│  │  │  └─ _.test.tsx          # Unit tests (Vitest + Testing Library)
+│  │  ├─ developers/            # Showcase profiles (excluded from coverage)
+│  │  └─ ui/                    # Internal building blocks (not public API)
+│  ├─ hooks/                    # Reusable hooks
+│  ├─ icons/                    # Icon components + types (excluded from coverage)
+│  ├─ lib/                      # Utilities shared by components
+│  ├─ index.ts                  # Library public exports
+│  ├─ index.css                 # Tailwind entry (built via PostCSS)
+│  └─ main.tsx                  # Local playground entry (not part of build output)
+├─ tests/setup.ts               # Vitest setup (jsdom, matchers)
+├─ vite.config.ts               # Vite + Vitest base config (alias '@' → './src')
+├─ vitest.config.ts             # Test include/exclude and coverage rules
+├─ eslint.config.js             # ESLint rules and TS integration
+├─ postcss.config.mjs           # PostCSS pipeline (imports, autoprefixer)
+├─ rollup.config.mjs            # Library bundle (esm/cjs/dts) for publish
+├─ package.json                 # Scripts, exports, deps, peer deps
+├─ dist/                        # Build output (ignored in dev)
+└─ public/                      # Static assets used by Storybook/demo
+```
+
+### Naming and File Conventions
+- Component folders are `PascalCase` and contain the standard set: `index.tsx`, `_.style.ts`, `_.types.ts` (or `type.ts`), `_.stories.tsx`, `_.test.tsx`.
+- Internal-only primitives live under `src/components/ui` and should not be exported from the library root.
+- The alias `@` resolves to `./src` (import like `import { cn } from '@/lib/utils'`).
+- CSS tokens live in `src/assets/style/*.css`; the library bundles `dist/style.css` (see exports in `package.json`).
+
+## Getting Started
+
+Prereqs: Node 18+ (or 20+), PNPM recommended.
+
+Install dependencies:
+```bash
+pnpm install
+```
+
+Run the dev playground (Vite):
+```bash
+pnpm dev
+```
+
+Open Storybook for component docs:
+```bash
+pnpm story
+```
+
+Run tests:
+```bash
+pnpm test
+```
+
+Run tests with coverage:
+```bash
+pnpm coverage
+```
+
+Lint the repo:
+```bash
+pnpm lint
+```
+
+Build the library (types + CSS + bundles):
+```bash
+pnpm build
+```
+
+Full release build (test → vite build → rollup):
+```bash
+pnpm rollup
+```
+
+## Exports and Consumers
+
+`package.json` exposes:
+- ESM: `dist/index.mjs`
+- CJS: `dist/index.js`
+- Types: `dist/index.d.ts`
+- CSS: `dist/style.css` (via subpath export)
+
+Consumers can:
+```tsx
+import { Button } from 'rg-dst';
+import 'rg-dst/dist/style.css';
+```
+
+## Adding a New Component
+
+1) Scaffold folder: `src/components/<ComponentName>/` with files:
+- `index.tsx` – component implementation
+- `_.types.ts` – define prop types; export `ComponentNameProps`
+- `_.style.ts` – class builders (e.g., with `class-variance-authority`) and helpers
+- `_.stories.tsx` – at least default and variants stories
+- `_.test.tsx` – render, states, a11y basics
+
+2) Implement component:
+- Keep public API small and typed. Prefer controlled props where appropriate.
+- Compose classes using `clsx`/`cva`. Do not inline large style strings.
+- Avoid leaking internal implementation details through props.
+
+3) Export from library:
+- Re-export from `src/components/index.ts` or `src/index.ts` according to the existing pattern.
+
+4) Document in Storybook:
+- Include controls for all public props.
+- Add usage notes and edge cases in stories or MDX docs.
+
+5) Tests:
+- Use `@testing-library/react` with JSDOM.
+- Cover critical behaviors, keyboard interactions, and edge states.
+- Place snapshots only for minimal structural assurance (avoid brittle snapshots).
+
+6) Styles and Tokens:
+- Reuse tokens from `src/assets/style/*` when possible.
+- If adding new primitive tokens, update CSS files with clear, scoped variables.
+
+## Updating an Existing Component
+
+1) Search for usages across stories, tests, and `src/components/ui` primitives before changing prop names or behavior.
+
+2) Maintain backward compatibility when feasible. If a breaking change is necessary:
+- Adjust stories and tests.
+- Update release notes and communicate migration steps in the PR description.
+
+3) Keep `_.types.ts` as the single source of truth for props and update stories/tests accordingly.
+
+4) Performance and a11y:
+- Use `React.memo`/`useMemo` only when it removes real work; avoid premature optimization.
+- Ensure focus management and ARIA attributes are correct (especially for interactive components).
+
+## Testing & Coverage
+
+Vitest is configured with JSDOM and global test APIs. Defaults:
+- Includes: `src/**/*.test.{ts,tsx}`, `src/**/*.spec.{ts,tsx}`
+- Excludes: `node_modules`, `dist`, `**/*.stories.tsx`, `**/*.style.ts`, `**/*.types.ts`, `src/icons/**/*.{ts,tsx}`
+
+Coverage includes `src/**/*.{ts,tsx}` with further excludes:
+- Stories, styles, types, icons
+- `src/components/developers/**`
+- `tests/**`, `dist/**`, `src/main.tsx`, `src/vite-env.d.ts`
+
+Command hints:
+```bash
+pnpm test            # run unit tests
+pnpm coverage        # generate text/json/html coverage
+```
+
+## Linting & Code Style
+
+ESLint rules are defined in `eslint.config.js`:
+- Typescript-eslint recommended rules
+- React hooks rules enforced
+- `@typescript-eslint/no-explicit-any` is disabled where pragmatic
+- `react-refresh/only-export-components` warned to keep HMR-friendly exports
+
+Guidelines:
+- Prefer clear, descriptive names over abbreviations.
+- Keep components focused; extract internal UI into `src/components/ui`.
+- Minimal comments; only for non-obvious rationale or caveats.
+- Early returns over deep nesting; avoid broad try/catch.
+
+## Styles & Theming
+
+- Tailwind via Vite plugin; utility composition preferred.
+- Shared tokens and utilities live in `src/assets/style/*.css`.
+- Library CSS is built with `pnpm build:css` to `dist/style.css`. Consumers must import it.
+
+## Icons
+
+- Add icons to `src/icons/general` as React components.
+- Keep icon types in `src/icons/icons.type.ts`.
+- Icons are excluded from test coverage; still add basic validation where necessary.
+
+## Aliases
+
+`@` → `./src` (configured in both `vite.config.ts` and `vitest.config.ts`). Example:
+```ts
+import { cn } from '@/lib/utils'
+```
+
+## Scripts (from package.json)
+
+- `pnpm dev` – Start Vite dev server (with `--host` for LAN testing)
+- `pnpm build:css` – Build `src/index.css` to `dist/style.css` via PostCSS
+- `pnpm build` – TypeScript build + CSS build + Vite build
+- `pnpm rollup` – Run tests, Vite build, and Rollup bundle (esm/cjs/dts)
+- `pnpm story` – Run Storybook on port 6006
+- `pnpm build-storybook` – Generate static Storybook
+- `pnpm test` – Run Vitest
+- `pnpm coverage` – Vitest with coverage
+- `pnpm lint` – Run ESLint
+
+## Publishing Notes
+
+- Ensure `peerDependencies` for `react` and `react-dom` are correct.
+- Verify `exports` map and `types` in `package.json`.
+- Run `pnpm rollup` and verify `dist/` contains `.mjs`, `.js`, `.d.ts`, and `style.css`.
+
+## Troubleshooting
+
+- Dev server fails to start
+  - Delete `node_modules` and lockfile, then `pnpm install`.
+  - Ensure Node version ≥ 18.
+
+- Storybook cannot resolve `@` alias
+  - Restart Storybook after changes to `vite.config.ts`.
+  - Confirm alias is set in both `vite.config.ts` and Storybook config (React-Vite preset handles this).
+
+- Tests fail with DOM-related errors
+  - Ensure `jsdom` environment is set (it is in config). Check `tests/setup.ts` path.
+
+- Coverage missing for new files
+  - Confirm files are within `src/` and not in an excluded pattern.
+
+- Styles not applied in consumer app
+  - Remind consumers to import `'rg-dst/dist/style.css'`.
+
+## Contribution Workflow
+
+1. Create a feature branch: `git checkout -b feat/<short-name>`
+2. Implement changes with stories and tests.
+3. Run `pnpm lint && pnpm test && pnpm build` locally.
+4. Open a PR with:
+   - Summary of changes
+   - Screenshots (stories) if visual
+   - Breaking changes and migration notes
+5. Request review; address feedback; squash and merge.
+
+---
+
+Questions or issues? Open an issue with context, repro steps, and environment details.

package/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}