@groupby/ai-dev 0.5.13 → 0.5.15

package/teams/brain-studio/skills/react/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: react
+description: >-
+  Provides project-specific React and JSX authoring rules for Command Center — function declarations
+  with explicit JSX.Element return types, no React.FC, no container/presenter split, PascalCase
+  component file naming, camelCase hook naming, styled-components (never CSS modules or Tailwind),
+  @/ path aliases, FormatJS i18n via useLocalization, logError error handling, and
+  useAppSelector/useAppDispatch from @/store/hooks. Auto-apply when creating, editing, reviewing,
+  or refactoring React components, hooks, or .tsx files in this repository.
+---
+
+# React Guide
+
+## Relationship to other repository skills
+
+- `javascript` skill — governs all JS-layer rules; read first for every `.tsx` file
+- `typescript` skill — governs TS-layer rules; read second for every `.tsx` file
+- `html` skill — governs accessible markup behaviour in JSX (roles, labels, keyboard)
+- `styled-components` skill — styled-components authoring rules for this project (colors, spacing, naming, transient props, overrides); read it for any styling work
+
+This skill does not replace javascript or typescript. It adds the React/JSX layer and all
+project-specific conventions that override or extend generic guidance.
+
+## Mandatory application (agents)
+
+Whenever the task involves React source — including `.tsx` files, custom hooks, component APIs, or
+Redux-connected components in this repository:
+
+1. **Read `javascript` skill first.**
+2. **Read `typescript` skill second** for any `.tsx` file.
+3. **Read this file third** for React/JSX decisions and project-specific rules.
+4. For a11y-heavy JSX, read `html` skill for label, button, and keyboard guidance.
+
+For strictly non-React files (`.ts` with no JSX, CSS-only, or plain HTML), this skill is optional.
+
+## When to use
+
+- Creating, editing, or reviewing React component `.tsx` files
+- Creating, editing, or reviewing custom hook `.ts` files
+- Questions about component structure, data-fetching pattern, or styling in this repo
+- File naming, import ordering, i18n, error handling, or state-access decisions in React code
+
+## When not to use
+
+- Pure `.ts` modules with no JSX → typescript skill
+- Styling-only work in `.styles.ts` files with no component logic changes → styled-components skill
+- Static `.html` files without React → html skill
+
+## Truthfulness and claims
+
+- Do not invent project file conventions — always defer to `docs/architecture/12-code-conventions/` (if present)
+- Do not recommend CSS Modules, Tailwind, or other CSS-in-JS alternatives — this project uses
+  styled-components exclusively
+- Do not recommend `React.FC`, `.container.tsx`, `.component.tsx`, or `use-x.hook.ts` suffixes —
+  these are legacy patterns; do not introduce them
+
+## Self-contained operating mode
+
+- Use the embedded standard below and `docs/architecture/` (if present) as the sole authorities for project
+  decisions
+- Do not fetch external React documentation for routine decisions; apply the react.dev mental model
+  embedded here
+- When `docs/architecture/` and generic React best-practice conflict, `docs/architecture/` wins
+- When project config (ESLint, `tsconfig.json`) and this skill conflict, project config wins; flag
+  the discrepancy rather than silently breaking the config
+
+---
+
+## Embedded implementation standard
+
+### 1) Component declaration
+
+- Use **function declarations** with an explicit `: JSX.Element` return type
+- Do **not** use arrow functions assigned to `const`, do **not** use `React.FC`
+- Guild standard — refactor `React.FC` patterns when touching existing files; do not introduce new ones
+
+```tsx
+// ✅ Correct — function declaration, explicit return type
+function RuleTable({ rules, onDelete }: RuleTableProps): JSX.Element {
+  return <StyledRuleTable>...</StyledRuleTable>;
+}
+
+// ❌ Legacy — do not introduce
+const RuleTable: React.FC<RuleTableProps> = ({ rules, onDelete }) => { /* ... */ };
+```
+
+### 2) Component structure
+
+- **No container/presenter split.** Do not create new `.container.tsx` or `.component.tsx` files.
+  - Extract business logic into custom hooks
+  - Use utility modules for pure data transformation
+  - Assemble via composition; keep the render tree flat and explicit
+- **Props.** Define with `interface Props { ... }` co-located in the component file. Extract to
+  `<entity>.model.ts` only when the type is shared across files.
+
+```tsx
+interface RuleTableProps {
+  rules: Rule[];
+  onDelete: (id: ModelId) => void;
+}
+```
+
+### 3) File and folder naming
+
+| File type | Convention | Example |
+|---|---|---|
+| React component | `PascalCase.tsx` | `RuleTable.tsx` |
+| Custom hook | `camelCase.ts` | `useConversionRateChartOptions.ts` |
+| Styled-components | `<entity>.styles.ts` | `rule-table.styles.ts` |
+| Model types | `<entity>.model.ts` | `rule.model.ts` |
+| Constants | `<entity>.constants.ts` | `filter-set-form.constants.ts` |
+| Context | `<name>.context.tsx` | `rule-form.context.tsx` |
+
+Legacy files use kebab-case with role suffixes (`.container.tsx`, `.component.tsx`,
+`use-x.hook.ts`). Rename to the conventions above when touching these files.
+
+### 4) Custom hooks
+
+- Name in `camelCase` without a `.hook.ts` suffix: `useRuleList.ts`, `useAbortRequest.ts`
+- Place in a `hooks/` subdirectory within the feature module, or `src/hooks/` for shared hooks
+- Always return a cleanup function from `useEffect` when registering subscriptions, timers, or
+  abort controllers:
+
+```tsx
+useEffect(() => {
+  const controller = new AbortController();
+
+  fetchData(controller.signal);
+
+  return () => {
+    controller.abort();
+  };
+}, []);
+```
+
+- Add `useCallback`/`useMemo`/`memo` only when measured or when stabilising reference identity is
+  required for dependency arrays — avoid premature memoisation
+
+### 5) Import style
+
+- Use `@/` path aliases for all cross-module imports — never use deep relative paths (`../../../../`)
+- Relative imports within the same module (`./rule-table`) are fine
+- **Import order:** React → third-party → `@/` → `./`
+- Named imports only; never import an entire library as a namespace
+
+```ts
+// ✅ Correct
+import React, { useCallback } from 'react';
+import { isEmpty } from 'ramda';
+import { useLocalization } from '@/localization';
+import { logError } from '@/utils/logger';
+import { RuleTableRow } from './RuleTableRow';
+
+// ❌ Avoid
+import * as R from 'ramda';
+import { useLocalization } from '../../../../localization';
+```
+
+### 6) Styling with styled-components
+
+This project uses **styled-components exclusively**. For the full styling standard, read
+`styled-components` skill. Key rules in brief:
+
+- Styled components live in a co-located **`.styles.ts`** file — never inline in the component file
+- Named exports use **PascalCase without a `Styled` prefix**: `Container`, `TableBodyContainer`
+- Colors from `baseColors` (`@groupby/ui-components`); spacing from `theme.spacing(N)` — never
+  hard-coded hex or `px` values
+- Styling-only props use the `$` prefix to prevent DOM forwarding
+- **Never `!important`** — use `&&` or child selectors for MUI overrides
+
+```ts
+import styled from 'styled-components';
+import { baseColors } from '@groupby/ui-components';
+
+// ✅ Correct
+export const Container = styled.div`
+  background-color: ${baseColors.background000};
+  padding: ${({ theme }) => theme.spacing(2)};
+`;
+
+export const TableBody = styled(MuiTableBody)<{ $loading: boolean }>`
+  ${({ $loading }) => $loading && `opacity: 0.5;`}
+`;
+
+// ❌ Legacy — do not introduce
+export const StyledContainer = styled.div`...`;
+```
+
+### 7) Internationalization (i18n)
+
+All user-facing strings **must** use FormatJS. Never hard-code English (or any language) text in JSX.
+
+```tsx
+import { useLocalization } from '@/localization';
+
+function MyComponent(): JSX.Element {
+  const { formatMessage: t } = useLocalization();
+
+  return <div>{t({ key: 'SOME_MESSAGE_KEY' })}</div>;
+}
+```
+
+After adding a new message key, run:
+
+```bash
+yarn messages:extract-and-compile
+```
+
+### 8) State management
+
+Use typed hooks from `@/store/hooks` — never bare `react-redux` imports:
+
+```ts
+import { useAppSelector, useAppDispatch } from '@/store/hooks'; // ✅
+import { useSelector, useDispatch } from 'react-redux';         // ❌
+```
+
+Access API data through **platform-services hooks** from `@/platform-services/<feature>` — never
+import RTK Query hooks from `@/store/api` directly in components or containers:
+
+```tsx
+import { useGetRuleList } from '@/platform-services/rules';     // ✅
+import { useGetRuleListQuery } from '@/store/api/cc/ruleApi';   // ❌
+```
+
+### 9) Error handling
+
+- Always use `logError` from `@/utils/logger` — never call Sentry directly
+- Use `isRequestAborted` from `@/client/utils` to distinguish intentional cancellations from errors;
+  skip error dispatch for aborted requests
+- Never log tokens, passwords, PII, or values from `window.__APP_CONFIG__`
+
+```ts
+import { logError } from '@/utils/logger';
+import { isRequestAborted } from '@/client/utils';
+
+try {
+  await updateRule(token, ruleData);
+
+  dispatch(addSuccess({ key: 'RULE_UPDATE_SUCCESS' }));
+} catch (error) {
+  if (!isRequestAborted(error)) {
+    logError('RULE_UPDATE_ERROR', error);
+    dispatch(addError({ key: 'RULE_UPDATE_ERROR' }));
+  }
+}
+```
+
+### 10) Keys, lists, and general React rules
+
+- **Keys on lists** must be stable among siblings — prefer opaque IDs from data; never use array
+  index when order or filtering can change identity
+- **Rules of Hooks**: call hooks only at the top level of React functions or custom hooks — never
+  inside loops, conditions, or nested functions
+- **One obvious owner** for shared state; prefer lifting state or composition over ad-hoc context
+- **Event handlers**: prefix with `handle*` (`handleClick`, `handleKeyDown`)
+
+---
+
+## Working method (apply in this order)
+
+1. **Confirm file type** — `.tsx` component, `.tsx` hook, or `.ts` utility?
+2. **Read skills in order**: javascript → typescript → this file.
+3. **Check component declaration**: function declaration with explicit `: JSX.Element`; no `React.FC`; no `.container.tsx` or `.component.tsx` files.
+4. **Apply file naming**: `PascalCase.tsx` for components, `camelCase.ts` for hooks; extract styled-components to `.styles.ts`.
+5. **Apply import order**: React → third-party → `@/` → `./`; use `@/` for all cross-module paths.
+6. **Replace hard-coded strings** with `useLocalization` calls; run `yarn messages:extract-and-compile` if new keys were added.
+7. **Verify state access**: `useAppSelector`/`useAppDispatch` from `@/store/hooks`; API data from `@/platform-services/<feature>` hooks only.
+8. **Verify error handling**: errors go through `logError`; aborted requests filtered via `isRequestAborted`.
+
+## Quality bar before final answer
+
+- All new component functions use `function Foo(props: FooProps): JSX.Element` — no arrow functions, no `React.FC`.
+- No `.container.tsx`, `.component.tsx`, or `use-x.hook.ts` file names introduced.
+- Styled-components are in a co-located `.styles.ts` file with `PascalCase` names and no `Styled` prefix.
+- No `!important` in styled-components.
+- All user-visible strings go through `useLocalization`; no hard-coded English text in JSX.
+- All Redux state access uses `useAppSelector`/`useAppDispatch` from `@/store/hooks`.
+- All API data access uses platform-services hooks from `@/platform-services/<feature>`.
+- Errors handled via `logError`; aborted requests filtered with `isRequestAborted`.
+- Import order is React → third-party → `@/` → `./`; no deep relative paths for cross-module imports.
+- Props typed as `interface FooProps { ... }`, co-located in the component file.

package/teams/brain-studio/skills/styled-components/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: styled-components
+description: >-
+  Provides project-specific styled-components authoring rules for Command Center — PascalCase named
+  exports (no Styled prefix), co-located .styles.ts files, baseColors from @groupby/ui-components
+  for colors, MUI theme.spacing() for spacing, $ transient props, no !important (use specificity
+  or && instead), and CSS fundamentals (layout, specificity, inheritance) as applied through the
+  styled-components API. Replaces the generic CSS skill for this repository — do not author plain
+  .css files or use CSS Modules/Tailwind. Auto-apply when creating, editing, reviewing, or
+  refactoring styled-components in any .styles.ts/.styles.tsx file, or when CSS-in-JS or styling
+  questions arise in this repository.
+---
+
+# Styled-Components Guide
+
+## Relationship to other repository skills
+
+- the react skill — governs component declaration, file naming, and the rule that
+  styled-components live in a co-located `.styles.ts` file; read it for component-level context
+- the typescript skill — governs TS types for styled-component prop shapes
+- the javascript skill — governs JS-layer formatting rules that apply to template
+  literals inside styled-components
+
+This skill does not replace react or typescript. It covers styling only.
+
+## Mandatory application (agents)
+
+Whenever the task involves styling in this repository — including `.styles.ts`, `.styles.tsx` files,
+or any `styled(...)` / `styled.div` call:
+
+1. **Read this file** for all styling decisions.
+2. **Read the react skill** for component-level placement rules (`.styles.ts`
+   co-location, naming conventions).
+3. **Do not** introduce plain `.css` files, CSS Modules, or Tailwind in this project.
+
+For a11y-aware styling (focus rings, contrast, reduced-motion), cross-read
+the html skill.
+
+## When to use
+
+- Creating or editing `.styles.ts` / `.styles.tsx` files
+- Adding `styled.div`, `styled(Component)`, or `css` helper calls anywhere in the codebase
+- Questions about colors, spacing, layout, specificity, or theming in this repo
+- Debugging styled-components output (generated class names, MUI theme, prop forwarding)
+
+## When not to use
+
+- Component logic with no styling changes → react skill
+- TypeScript prop-shape questions with no CSS involvement → typescript skill
+
+## Truthfulness and claims
+
+- Do not recommend plain `.css` files, CSS Modules, or Tailwind — this project uses
+  styled-components exclusively
+- Do not recommend hard-coded hex values or pixel sizes — all colors must come from `baseColors`,
+  all spacing from `theme.spacing()`
+- Do not invent browser support percentages or claim one global "most popular" CSS approach
+- For uncertain edge behaviour in CSS properties, flag for verification in browser devtools rather
+  than guessing
+
+## Self-contained operating mode
+
+- Use the embedded standard below and `docs/architecture/12-code-conventions/` as the sole
+  authorities for project styling decisions
+- Do not fetch external styled-components documentation for routine decisions
+- When `docs/architecture/` and generic styled-components best-practice conflict,
+  `docs/architecture/` wins
+- When project tooling conflicts with this skill, project tooling wins; flag the discrepancy
+
+---
+
+## Embedded implementation standard
+
+### 1) File placement and structure
+
+- Styled components live in a **co-located `.styles.ts`** file — never inline in the component file
+- Use `.styles.tsx` only when the `css` helper contains JSX
+- Never put styled-component definitions inside `*.tsx` component files
+
+```
+RuleTable.tsx            ← component logic only
+rule-table.styles.ts     ← all styled-components for RuleTable
+```
+
+### 2) Naming
+
+- Named exports use **PascalCase without a `Styled` prefix**: `Container`, `TableBodyContainer`,
+  `RuleFormContainer`
+- Do **not** introduce new `StyledXxx` names
+- When refactoring existing `StyledXxx` names, remove the prefix
+
+```ts
+// ✅ Correct
+export const Container = styled.div`...`;
+export const TableBodyContainer = styled.div`...`;
+
+// ❌ Legacy — do not introduce
+export const StyledContainer = styled.div`...`;
+```
+
+### 3) Colors
+
+- Always use **`baseColors`** from `@groupby/ui-components` — never hard-code hex values, `rgb()`,
+  or `hsl()` literals
+- `baseColors` maps to the GroupBy design system; using it directly means theme changes propagate
+  automatically
+
+```ts
+import { baseColors } from '@groupby/ui-components';
+
+// ✅ Correct
+export const Container = styled.div`
+  background-color: ${baseColors.background000};
+  color: ${baseColors.midnight800};
+  border: 1px solid ${baseColors.midnight200};
+`;
+
+// ❌ Banned
+export const Container = styled.div`
+  background-color: #fff;
+  color: #1a2332;
+`;
+```
+
+### 4) Spacing
+
+- Use the **MUI theme** for spacing — never hard-code pixel sizes that should track the design
+  system
+- Access via the `theme` prop callback: `${({ theme }) => theme.spacing(N)}`
+
+```ts
+// ✅ Correct — spacing from theme
+export const Card = styled.div`
+  padding: ${({ theme }) => theme.spacing(2)};
+  margin-bottom: ${({ theme }) => theme.spacing(1)};
+`;
+
+// ❌ Banned — hard-coded spacing
+export const Card = styled.div`
+  padding: 16px;
+  margin-bottom: 8px;
+`;
+```
+
+**Exceptions:** pixel values are acceptable for border widths (`1px`), border-radius where no theme
+token exists, and `0`.
+
+### 5) Transient props
+
+- Use the **`$` prefix** for props that control styling but must **not** be forwarded to the DOM
+  element
+- Prevents React DOM prop warnings for boolean and custom props
+
+```ts
+// ✅ Correct — $ prefix keeps $loading off the DOM
+export const TableBody = styled(MuiTableBody)<{ $loading: boolean }>`
+  ${({ $loading }) => $loading && `opacity: 0.5;`}
+`;
+
+// ❌ Will cause React DOM warning — remove $ prefix
+export const TableBody = styled(MuiTableBody)<{ loading: boolean }>`
+  ${({ loading }) => loading && `opacity: 0.5;`}
+`;
+```
+
+### 6) Overriding MUI components
+
+When styling a MUI component with styled-components, MUI's internal specificity can conflict. Resolve
+in this order of preference:
+
+1. **Target the MUI class directly** — use the component's stable `Mui*-root` / `Mui*-*` class
+   names as child selectors when you need to reach internal elements:
+
+   ```ts
+   export const CustomTextField = styled(TextField)`
+     .MuiInputBase-root {
+       border-radius: 8px;
+     }
+   `;
+   ```
+
+2. **Double-ampersand specificity boost** — when the above is not enough, `&&` doubles the
+   generated class, beating MUI's specificity without `!important`:
+
+   ```ts
+   export const CustomInput = styled(Input)`
+     && {
+       flex: none;
+     }
+   `;
+   ```
+
+3. **Refactor the layout** — if you are reaching for overrides at all, the real issue is usually in
+   the container structure.
+
+### 7) No `!important`
+
+**Never use `!important`** in styled-components or anywhere in this codebase.
+
+`!important` breaks specificity predictability, creates competing overrides, and makes styles brittle
+during refactoring.
+
+```ts
+// ❌ Banned
+export const CustomInput = styled(Input)`
+  flex: 0 1 500px !important;
+`;
+
+// ✅ Use && specificity boost instead
+export const CustomInput = styled(Input)`
+  && {
+    flex: none;
+  }
+`;
+```
+
+### 8) Conditional and dynamic styles
+
+Two patterns — choose the one that reads most clearly:
+
+```ts
+// Inline ternary — for single-property conditions
+export const Badge = styled.span<{ $active: boolean }>`
+  background-color: ${({ $active }) => $active ? baseColors.green500 : baseColors.midnight200};
+`;
+
+// css helper — for multi-property conditions (import from styled-components)
+import styled, { css } from 'styled-components';
+
+export const Row = styled.div<{ $selected: boolean }>`
+  padding: ${({ theme }) => theme.spacing(1)};
+
+  ${({ $selected }) =>
+    $selected &&
+    css`
+      background-color: ${baseColors.primary100};
+      font-weight: 600;
+    `}
+`;
+```
+
+### 9) Extending components
+
+- Use `styled(Component)` to extend an existing styled-component or MUI component
+- Prefer extension over copy-pasting styles
+
+```ts
+// ✅ Extending an existing component
+export const PrimaryButton = styled(Button)`
+  background-color: ${baseColors.primary500};
+`;
+
+// ✅ Extending another styled-component from the same file
+export const LargeContainer = styled(Container)`
+  padding: ${({ theme }) => theme.spacing(4)};
+`;
+```
+
+### 10) CSS layout fundamentals inside template literals
+
+Standard CSS layout rules apply verbatim inside styled-components template literals.
+
+**Flexbox (one axis):**
+
+```ts
+export const Toolbar = styled.div`
+  display: flex;
+  align-items: center;
+  gap: ${({ theme }) => theme.spacing(1)};
+`;
+```
+
+**Grid (two axes):**
+
+```ts
+export const DashboardGrid = styled.div`
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+  gap: ${({ theme }) => theme.spacing(2)};
+`;
+```
+
+- Prefer **`gap`** over margins between flex/grid children
+- Use **`min-width: 0`** on flex/grid children that must shrink and clip text correctly
+- No negative margins — use `gap`, `padding`, or layout structure instead
+
+### 11) Specificity and cascade
+
+- Each styled-component generates a **single unique class** — specificity is always one class
+  (0-1-0). There are no selector chains unless you write them explicitly.
+- Nested selectors (e.g. `.MuiInputBase-root`) add a class-level specificity increment for each
+  class token in the chain — keep nesting intentional and minimal.
+- When overriding MUI, styled-components specificity often loses to MUI's inline-on-render styles.
+  Resolve with `&&` (section 6) before reaching for anything else.
+
+### 12) Accessibility-aware styling
+
+- Never remove `outline` on `:focus` without a visible, accessible replacement using `:focus-visible`
+- Contrast: UI text must meet WCAG 2.2 — at least **4.5:1** for normal text, **3:1** for large text
+  and UI components — use `baseColors` tokens which are calibrated to the design system
+- Respect `prefers-reduced-motion` for animation-heavy components:
+
+```ts
+export const AnimatedPanel = styled.div<{ $open: boolean }>`
+  transition: transform 0.3s ease;
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+`;
+```
+
+---
+
+## Working method (apply in this order)
+
+1. **Confirm placement** — does a `.styles.ts` co-located file already exist? Create it if not.
+2. **Name the export** — PascalCase, no `Styled` prefix; rename legacy `StyledXxx` names when touching them.
+3. **Pick the base** — `styled.div` / `styled.span` / etc. for HTML elements; `styled(MuiComponent)` for MUI; `styled(ExistingStyledComponent)` for extension.
+4. **Apply colors** from `baseColors`; apply spacing from `theme.spacing(N)` — no hard-coded hex or pixel values.
+5. **Add transient props** with `$` prefix for any prop that controls style but must not reach the DOM.
+6. **For overrides** use child selectors → `&&` → refactor layout (never `!important`).
+7. **Check accessibility** — focus styles intact, sufficient contrast, reduced-motion respected.
+
+## Quality bar before final answer
+
+- Styled components are in a co-located `.styles.ts` file, never inline in `.tsx`.
+- All exports are PascalCase with no `Styled` prefix.
+- All color values come from `baseColors`; no hard-coded hex, `rgb()`, or `hsl()` literals.
+- All spacing comes from `theme.spacing()`; no hard-coded `px` sizes (except `0`, `1px` borders, border-radius).
+- All styling-only props use the `$` prefix.
+- No `!important` anywhere; specificity conflicts resolved with `&&` or child selectors.
+- No plain `.css` files, CSS Modules, or Tailwind introduced.
+- Negative margins are absent; layout spacing uses `gap` or `padding`.
+- Focus styles are present and accessible on interactive elements.
+