Develop

.agent/rules/ia-rules.md

@@ -0,0 +1,109 @@
+---
+trigger: always_on
+---
+
+# AI Guidelines for OpenTimeTracker
+
+This document provides context and rules for AI agents contributing to OpenTimeTracker. Follow these guidelines to ensure consistency, quality, and adherence to project standards.
+
+## Project Overview
+
+- **Name**: OpenTimeTracker
+- **Purpose**: Free, open-source, local-first time tracking application.
+- **Key Features**: Offline-first (SQLite), no subscriptions, cross-platform (Windows, macOS, Linux).
+
+## Tech Stack
+
+- **Frontend**: Angular 21 (Signals, Standalone Components, strict mode).
+- **Desktop Wrapper**: Electron 37 (IPC for Node.js access).
+- **Database**: SQLite via Prisma (local file `timetracker.db`).
+- **UI Component Library**: PrimeNG 21 + PrimeFlex.
+- **State Management**: Angular Signals + Services (avoid NgRx unless strictly necessary).
+- **Internationalization**: `@ngx-translate/core`.
+
+## Coding Standards
+
+### TypeScript & Angular
+
+- **Strict Typing**: No `any`. Define interfaces for all data structures.
+- **Signals**: Use Angular Signals for state reactivity. Avoid `BehaviorSubject` where Signals suffice.
+- **Standalone Components**: All new components must be `standalone: true`.
+- **Control Flow**: Use modern Angular control flow (`@if`, `@for`, `@switch`) instead of `*ngIf`, `*ngFor`.
+- **Change Detection**: Use `OnPush` strategy where possible.
+
+### Electron & IPC
+
+- **Security**: Enable context isolation and sandbox.
+- **IPC**: Use `ipcMain.handle` and `ipcRenderer.invoke` for bidirectional communication.
+- **Preload Scripts**: Expose typed APIs via `contextBridge`.
+
+### CSS & Styling
+
+- **PrimeFlex**: Use PrimeFlex utility classes for layout and spacing (e.g., `flex`, `gap-2`, `p-3`).
+- **SCSS**: Use component-specific SCSS for custom styles not covered by PrimeFlex.
+- **Variables**: Use CSS variables for theming (e.g., `var(--primary-color)`).
+
+### Git & Commits
+
+- **Conventional Commits**: `type(scope): description`.
+  - Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
+  - Example: `feat(calendar): add weekly view support`.
+
+## Architecture
+
+### Directory Structure
+
+- `src/app`: Angular application code.
+- `src/assets`: Static assets and i18n files.
+- `electron/src`: Electron main process and preload scripts.
+- `electron/src/services`: IPC handlers and Node.js logic.
+- `prisma`: Database schema and migrations.
+
+### Internationalization (i18n)
+
+- All user-facing text must be translatable.
+- Keys: `SECTION.FEATURE.KEY` (e.g., `SETTINGS.UPDATES.CHECK_NOW`).
+- Files: `src/assets/i18n/en.json`, `src/assets/i18n/es.json`.
+- Tools: `TranslateService`, `TranslatePipe`.
+
+### Testing
+
+- **Unit Tests**: Jasmine + Karma (Angular), Vitest (Electron).
+- **Coverage**: Maintain high coverage (>80%).
+- **SonarQube**: Respect quality gates. Run `npm run sonar:check` before pushing.
+
+### UI Development (Storybook)
+
+- Create stories for new dumb/presentational components.
+- Path: `src/app/components/[name]/[name].stories.ts`.
+- Run: `npm run storybook`.
+
+## Workflows
+
+### Database Changes
+
+1. Modify `prisma/schema.prisma`.
+2. Run `npx prisma migrate dev --name <migration_name>`.
+3. Run `npm run prisma:template` to update production template.
+
+### Adding a New Feature
+
+1. Design component/service hierarchy.
+2. Implement core logic and state.
+3. Add UI with PrimeNG/PrimeFlex.
+4. Add i18n keys to English and Spanish.
+5. Add Unit Tests.
+6. (Optional) Add Storybook story.
+7. Verify with `npm run sonar:check`.
+
+## Context for AI
+
+- **Do not** suggest cloud-based solutions unless explicitly asked (Local-first philosophy).
+- **Do not** introduce new heavy dependencies without approval.
+- **Always** check `package.json` scripts (`dev`, `build`, `test`, `sonar:check`) for running tasks.
+- **Always** favor modern Angular syntax (Signals, Control Flow).
+
+## Essential Commands
+
+- **Run Project**: `npm run dev` (Runs Angular + Electron in development mode).
+- **Run Tests & Quality Checks**: `npm run sonar:check` (Runs Unit Tests, Coverage, and SonarQube analysis). Use this to verify your changes.

.storybook/main.ts

@@ -1,12 +1,21 @@
 import type { StorybookConfig } from '@storybook/angular';
 
 const config: StorybookConfig = {
-  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
-  addons: [
-    '@storybook/addon-a11y',
-    '@storybook/addon-docs',
-    '@storybook/addon-onboarding',
+  stories: [
+    './*.mdx',
+    '../src/**/*.mdx',
+    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)',
   ],
-  framework: '@storybook/angular',
+  addons: ['@storybook/addon-a11y', '@storybook/addon-docs'],
+  framework: {
+    name: '@storybook/angular',
+    options: {},
+  },
+  staticDirs: ['../public'],
+  /* Explicitly include global styles from Angular project */
+  previewHead: (head) => `
+    ${head}
+    <link rel="stylesheet" href="https://unpkg.com/primeicons@7.0.0/primeicons.css">
+  `,
 };
 export default config;

.storybook/preview.ts

@@ -1,16 +1,99 @@
 import type { Preview } from '@storybook/angular';
 import { setCompodocJson } from '@storybook/addon-docs/angular';
+import { applicationConfig } from '@storybook/angular';
 import docJson from '../documentation.json';
+
+/* Import PrimeNG configuration */
+import { provideAnimations } from '@angular/platform-browser/animations';
+import { providePrimeNG } from 'primeng/config';
+import { AuraOpen } from '../src/app/themes/aura-open.preset';
+
+/* Import i18n configuration */
+import { importProvidersFrom } from '@angular/core';
+import { TranslateModule, TranslateLoader } from '@ngx-translate/core';
+import { of } from 'rxjs';
+
+/*
+ * Mock TranslateLoader for Storybook
+ * Empty - all translations are handled in individual stories
+ */
+class StoryTranslateLoader implements TranslateLoader {
+  getTranslation() {
+    return of({});
+  }
+}
+
 setCompodocJson(docJson);
 
 const preview: Preview = {
+  decorators: [
+    applicationConfig({
+      providers: [
+        provideAnimations(),
+        providePrimeNG({
+          theme: {
+            preset: AuraOpen,
+            options: {
+              darkModeSelector: '.my-app-dark',
+              cssLayer: false,
+            },
+          },
+          inputVariant: 'outlined',
+          ripple: true,
+        }),
+        importProvidersFrom(
+          TranslateModule.forRoot({
+            defaultLanguage: 'es',
+            loader: {
+              provide: TranslateLoader,
+              useClass: StoryTranslateLoader,
+            },
+          }),
+        ),
+      ],
+    }),
+    (story, context) => {
+      /* Handle theme switching from story args */
+      const theme = context.args['theme'] || 'dark';
+      if (theme === 'dark') {
+        document.documentElement.classList.add('my-app-dark');
+        document.documentElement.classList.remove('my-app-light');
+      } else {
+        document.documentElement.classList.remove('my-app-dark');
+        document.documentElement.classList.add('my-app-light');
+      }
+
+      /*
+       * Handle language switching from story args
+       * Note: TranslateService is configured with the selected locale
+       * Components using computed signals with translate.instant() will
+       * need to use the locale from args in their render functions
+       */
+      const locale = context.args['locale'] || 'es';
+
+      return story({ locale });
+    },
+  ],
   parameters: {
     controls: {
       matchers: {
         color: /(background|color)$/i,
         date: /Date$/i,
       },
     },
+    backgrounds: {
+      default: 'dark',
+      values: [
+        {
+          name: 'dark',
+          value: '#09090b',
+        },
+        {
+          name: 'light',
+          value: '#ffffff',
+        },
+      ],
+    },
   },
 };
 

COLLABORATION.md

@@ -23,6 +23,7 @@ Brief guide to contribute consistently. English first, Spanish version below.
    ```bash
    npm start            # Angular dev server on 4200
    npm run dev          # build + Electron dev mode
+   npm run storybook    # UI component explorer
    ```
 
 ## Workflow
@@ -68,6 +69,7 @@ Brief guide to contribute consistently. English first, Spanish version below.
 ## UI and i18n
 
 - Uses PrimeNG/PrimeFlex, dark theme by default.
+- Use Storybook to develop components in isolation.
 - Add strings in src/assets/i18n/en.json and src/assets/i18n/es.json.
 - Mind accessibility: labels, visible focus, contrast.
 
@@ -113,6 +115,7 @@ Guía breve para contribuir de forma consistente.
    ```bash
    npm start            # servidor Angular en 4200
    npm run dev          # build + Electron en modo desarrollo
+   npm run storybook    # explorador de componentes UI
    ```
 
 ### Flujo de trabajo
@@ -158,6 +161,7 @@ Guía breve para contribuir de forma consistente.
 ### UI e i18n
 
 - Componentes con PrimeNG/PrimeFlex, tema oscuro por defecto.
+- Usa Storybook para desarrollar componentes de forma aislada.
 - Añade cadenas en src/assets/i18n/en.json y src/assets/i18n/es.json.
 - Cuida accesibilidad: labels, focus visible, contrastes.
 

CONTRIBUTING.md

@@ -254,6 +254,13 @@ When modifying the Prisma schema:
 - Dark theme (Aura Black) is the default
 - Follow existing component patterns
 
+* +### Storybook
+* +We use [Storybook](https://storybook.js.org/) for UI component development and documentation.
+* +- **Run Storybook**: `npm run storybook` (accessible at http://localhost:6006)
+  +- **Build Storybook**: `npm run build-storybook`
+  +- **Creating Stories**: Add `*.stories.ts` files alongside your components.
+  +- **Documentation**: Storybook documentation is auto-generated using Compodoc. Ensure `documentation.json` is up-to-date if you encounter issues.
+
 ### Adding Translations
 
 Add new strings to both language files:
@@ -540,6 +547,13 @@ Al modificar el esquema de Prisma:
 - El tema oscuro (Aura Black) es el predeterminado
 - Sigue los patrones de componentes existentes
 
+* +### Storybook
+* +Usamos [Storybook](https://storybook.js.org/) para el desarrollo y documentación de componentes de UI.
+* +- **Ejecutar Storybook**: `npm run storybook` (accesible en http://localhost:6006)
+  +- **Construir Storybook**: `npm run build-storybook`
+  +- **Crear Historias**: Añade archivos `*.stories.ts` junto a tus componentes.
+  +- **Documentación**: La documentación de Storybook se genera automáticamente usando Compodoc. Asegúrate de que `documentation.json` esté actualizado si encuentras problemas.
+
 ### Añadir Traducciones
 
 Añade nuevas cadenas a ambos archivos de idioma:

README.md

@@ -82,6 +82,9 @@ cd OpenTimeTracker
 npm install
 npm run prisma:generate
 npm run dev
+
+# Run Storybook (Component Explorer)
+npm run storybook
 ```
 
 npm run dev is the recommended and supported development command.
@@ -105,6 +108,8 @@ All contribution-related documentation lives outside this README to keep things
 
 🧭 COLLABORATION.md — technical and architectural details
 
+🤖 AI_GUIDELINES.md — context and rules for AI assistants
+
 🛡️ SECURITY.md — how to report vulnerabilities
 
 📜 CODE_OF_CONDUCT.md — community guidelines