@ngrr/ds 0.1.29 → 0.1.31

package/AGENTS.md

@@ -1,461 +0,0 @@
-# DS-Nagarro Component Library — Building Guide
-
-> **READ THIS FIRST.** This file is the entry point for every coding session on the component library.
-> Do not write any code until you have read and understood this document.
->
-> **This file is for building components.** For component usage specs, layout rules, and
-> navigation patterns when building apps *with* `@ngrr/ds`, read `AI.md` instead.
-
----
-
-## Project Purpose
-
-This is the React component library for **DS-Nagarro**, an enterprise design system optimised for AI-agent code generation. The primary goal is machine-readable fidelity: components must implement exactly what the design system specifies, using exactly the tokens named in the documentation. No creative interpretation.
-
----
-
-## Stack
-
-| Layer | Technology |
-|---|---|
-| Framework | React 18 + TypeScript |
-| Build | Vite |
-| Styling | Styled Components v6 |
-| Token consumption | CSS custom properties via `var()` |
-| Documentation | Storybook 8 (CSF 3.0 + autodocs) |
-| Testing | Vitest + Testing Library + Storybook play functions |
-
----
-
-## Repository Structure
-
-```
-ds-nagarro/
-├── AGENTS.md                    ← You are here (building guide)
-├── AI.md                        ← Usage guide (for consuming the package)
-├── CLAUDE.md                    ← Claude Code pointer (redirects here)
-├── tokens.css                   ← All design tokens as CSS custom properties
-├── src/
-│   ├── index.ts                 ← Public API — export all components
-│   ├── styles/
-│   │   └── global.css           ← Imports tokens.css, sets base styles
-│   ├── components/
-│   │   ├── atoms/
-│   │   │   ├── Button/
-│   │   │   │   ├── Button.tsx
-│   │   │   │   ├── Button.stories.tsx
-│   │   │   │   ├── Button.test.tsx
-│   │   │   │   └── index.ts
-│   │   │   └── [other atoms...]
-│   │   ├── molecules/
-│   │   └── organisms/
-│   └── types/
-│       └── common.ts            ← Shared TypeScript interfaces
-├── .storybook/
-│   ├── main.ts
-│   └── preview.ts               ← Imports tokens.css globally
-└── docs/                        ← Design system documentation (read-only)
-    └── [component spec files — see table below]
-```
-
----
-
-## Component Documentation
-
-All component specs live in the `docs/` directory. Each file is authoritative for its component(s). Read the relevant doc **before** generating any component.
-
-| File | Components covered |
-|---|---|
-| `button.md` | Button (Main, Destructive, Toggle, Vertical) |
-| `avatar.md` | Avatar, AvatarGroup |
-| `badge.md` | Badge |
-| `tag.md` | Tag |
-| `chip.md` | Chip, ChipGroup |
-| `separator.md` | Separator |
-| `switcher.md` | Switcher (Toggle Switch) |
-| `checkbox.md` | Checkbox |
-| `radio.md` | Radio |
-| `tab.md` | Tab (Navigation, Custom View) |
-| `segment-control.md` | SegmentControl |
-| `breadcrumbs.md` | Breadcrumbs, BreadcrumbItem |
-| `pagination.md` | Pagination, PageSelector |
-| `toast.md` | Toast (Inline, Rich) |
-| `tooltip.md` | Tooltip |
-| `popover.md` | Popover |
-| `modal.md` | Modal |
-| `input-anatomy.md` | Input anatomy (shared across all input types) |
-| `input-text-textarea-search.md` | TextInput, TextArea, SearchInput |
-| `input-password-otp-number-phone.md` | PasswordInput, OTPInput, NumberInput, PhoneInput |
-| `input-select-autocomplete-horizontal.md` | Select, AutocompleteMulti, HorizontalInput |
-| `input-slider-upload-chips.md` | Slider, UploadArea, ChipsInput |
-| `input-date-time-picker.md` | DatePicker, DateRangePicker, DateTimePicker |
-| `lightweight-loading-scrollbar-shortcut.md` | Spinner, SkeletonLoading, ProgressBar, Scrollbar, Shortcut |
-| `patterns.md` | Layout patterns (not components) |
-| `foundations.md` | Token system, colour rules, typography rules |
-| `ds-guidelines.md` | Global rules |
-
----
-
-## Token System
-
-### Where tokens live
-All tokens are CSS custom properties defined in `tokens.css`. They are imported globally via `src/styles/global.css`. Every Styled Component must consume tokens via `var(--token-name)`.
-
-### Naming convention
-Figma uses slash-separated paths. These map directly to hyphen-separated CSS custom properties:
-
-```
-Figma:  background/interactive/cta/default
-CSS:    var(--background-interactive-cta-default)
-
-Figma:  font/size/body-l
-CSS:    var(--font-size-body-l)
-
-Figma:  borders/focus/primary
-CSS:    var(--borders-focus-primary)
-
-Figma:  color-text-primary
-CSS:    var(--color-text-primary)
-```
-
-### Three-tier model
-```
-Layer 1: Primitives     --primitive-neutral-900    (never use in components)
-Layer 2: Semantic       --color-text-primary        (use in components)
-Layer 3: Component      --color-surface-button-*    (component-specific overrides)
-```
-
-**Always use Layer 2 (semantic) tokens in components. Never reference Layer 1 (primitive) tokens directly in component styles.**
-
-### Key token families
-- `--color-text-*` → CSS `color` property
-- `--background-*` → CSS `background-color` property
-- `--borders-*` → CSS `border-color`, `outline-color`
-- `--color-surface-*` → component-specific background fills
-- `--color-dataviz-*` → all chart and data visualisation colors (series, axes, labels, backgrounds). Never use generic semantic tokens or hardcoded hex values for dataviz.
-- `--font-size-*`, `--font-weight-*`, `--font-line-height-*` → typography
-- `--space-*` → layout gaps (margin, gap) — between elements
-- `--inset-*` → component padding — inside components
-- `--page-margin-x` → horizontal spacing for all containers (pages, cards, modals, drawers, tables, lists, form sections). Always use this token. Never hardcode `padding-left`, `padding-right`, `margin-left`, or `margin-right`.
-- `--radius-*` → border-radius
-- `--border-width-*` → border-width
-- `--effects-elevation-*` → box-shadow
-- `--transition-*` → transition
-
----
-
-## Component Generation Rules
-
-### Rule 1: Props = Figma variant properties
-Figma variant property names map directly to React prop names. Match them exactly.
-
-```
-Figma: Size=Medium, Variant=Primary, State=Default, Disabled=False, Loading=False
-React: size="md" variant="primary" state="default" disabled={false} loading={false}
-```
-
-Size name mapping (Figma → prop value):
-- `Small` → `"sm"`
-- `Medium` → `"md"`
-- `Large` → `"lg"`
-- `xLarge` → `"xl"`
-- `xxLarge` → `"2xl"`
-
-Boolean props extracted from Figma booleans:
-- `Disabled=True/False` → `disabled?: boolean`
-- `Loading=True/False` → `loading?: boolean`
-- `Selected=True/False` → `selected?: boolean`
-
-State is internal — never accept `state` as a prop. States are expressed via pseudo-classes and boolean props only.
-
-### Rule 2: TypeScript interfaces — explicit union types
-Every prop that corresponds to a Figma variant must be a TypeScript union type (not `string`).
-
-```typescript
-// CORRECT
-export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'plain';
-export type ButtonSize = 'sm' | 'md';
-
-// WRONG
-variant: string;
-size: string;
-```
-
-### Rule 3: Styled Components — tokens only, no hardcoded values
-No hex codes, no pixel values, no hardcoded rgba. Everything comes from tokens.
-
-```typescript
-// CORRECT
-background-color: var(--background-interactive-cta-default);
-font-size: var(--font-size-body-l);
-padding-inline: var(--page-margin-x);
-
-// WRONG
-background-color: #6941C6;
-font-size: 16px;
-padding: 0 24px;
-```
-
-### Rule 4: State implementation
-Interactive states use CSS pseudo-classes + `data-*` attributes. Never conditionally render different DOM elements for states.
-
-```typescript
-// Hover, press, focus — CSS pseudo-classes
-&:hover:not(:disabled) {
-  background-color: var(--background-interactive-cta-hover);
-}
-&:active:not(:disabled) {
-  background-color: var(--background-interactive-cta-pressed);
-}
-&:focus-visible {
-  outline: var(--border-width-focus) solid var(--borders-focus-primary);
-  outline-offset: 2px;
-}
-&:disabled {
-  opacity: 1; /* Never use opacity for disabled — use explicit disabled tokens */
-  background-color: var(--background-disabled);
-  color: var(--color-text-disabled);
-  cursor: not-allowed;
-}
-
-// Selected state — controlled via prop → data attribute
-const StyledButton = styled.button<{ $selected?: boolean }>`
-  background-color: ${({ $selected }) =>
-    $selected
-      ? 'var(--background-selected-strong)'
-      : 'var(--background-interactive-default-default)'
-  };
-`;
-```
-
-Use `$` prefix (transient props) for all Styled Components props that should not reach the DOM.
-
-### Rule 5: Focus states — always `:focus-visible`, never `:focus`
-```typescript
-// CORRECT
-&:focus-visible { outline: ... }
-
-// WRONG
-&:focus { outline: ... }
-// NEVER
-outline: none; /* without explicit replacement */
-```
-
-### Rule 6: Semantic HTML and ARIA
-Every component must use the correct HTML element and ARIA attributes. The Figma file cannot express this — the component docs are the source of truth.
-
-```typescript
-// Buttons
-<button type="button" disabled={disabled} aria-pressed={selected} aria-busy={loading}>
-
-// Form inputs — every input is mandatory by default
-// Do NOT mark required fields with an asterisk
-// Only add an "Optional" label (in var(--text-tertiary)) for fields that are not mandatory
-<input
-  type="text"
-  id={id}
-  aria-label={ariaLabel}
-  aria-describedby={helpTextId}
-  aria-invalid={error}
-  aria-required={true}   // all inputs mandatory by default; omit or set false for optional
-/>
-<label htmlFor={id}>{label}</label>
-
-// Loading state
-aria-busy="true"
-aria-label="Loading..."
-```
-
-### Rule 7: Storybook — CSF 3.0 format
-```typescript
-// Button.stories.tsx pattern
-import type { Meta, StoryObj } from '@storybook/react';
-import { Button } from './Button';
-
-const meta: Meta<typeof Button> = {
-  title: 'Atoms/Button',
-  component: Button,
-  tags: ['autodocs'],
-  argTypes: {
-    variant: {
-      control: 'select',
-      options: ['primary', 'secondary', 'ghost', 'plain'],
-    },
-    size: {
-      control: 'select',
-      options: ['sm', 'md'],
-    },
-  },
-};
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-// One story per meaningful variant combination
-export const Primary: Story = { args: { variant: 'primary', size: 'md', children: 'Button' } };
-export const Secondary: Story = { args: { variant: 'secondary', size: 'md', children: 'Button' } };
-export const Disabled: Story = { args: { variant: 'primary', size: 'md', disabled: true, children: 'Button' } };
-export const Loading: Story = { args: { variant: 'primary', size: 'md', loading: true, children: 'Button' } };
-
-// Interaction test example
-export const FocusInteraction: Story = {
-  args: { variant: 'primary', children: 'Focus me' },
-  play: async ({ canvasElement }) => {
-    const canvas = within(canvasElement);
-    const button = canvas.getByRole('button');
-    await userEvent.tab();
-    expect(button).toHaveFocus();
-  },
-};
-```
-
-### Rule 8: File structure — one directory per component
-```
-Button/
-├── Button.tsx          ← Component implementation
-├── Button.stories.tsx  ← All stories for this component
-├── Button.test.tsx     ← Unit tests
-└── index.ts            ← Re-exports: export { Button } from './Button';
-```
-
-### Rule 9: Component generation order (atoms first)
-1. **Button** (covers: Main, Destructive, Toggle, Vertical)
-2. **Avatar** + **AvatarGroup**
-3. **Badge**
-4. **Tag**
-5. **Chip** + **ChipGroup**
-6. **Separator**
-7. **Switcher**
-8. **Checkbox**
-9. **Radio**
-10. **TextInput** (and shared Input anatomy)
-11. **TextArea**
-12. **SearchInput**
-13. **Select**
-14. **Slider**
-15. **Tab** (Navigation + Custom View)
-16. **SegmentControl**
-17. **Breadcrumbs**
-18. **Pagination**
-19. **Toast**
-20. **Tooltip**
-21. **Popover**
-22. **Modal**
-23. Remaining input types (Password, OTP, Number, Phone, DatePicker, etc.)
-
-### Rule 10: Dropdown/popover positioning contract
-All dropdown/select/popover menus must use the shared anchored behavior (via `PopoverWrapper`):
-- Default placement: below trigger
-- Gap: `var(--space-tiny)`
-- Flip: only when not enough room below
-- Viewport safe margin: `var(--space-medium)` from all edges
-- Horizontal clamping: keep popovers within safe viewport bounds
-- Width contract: match trigger width with a minimum popover width of `192px`
-- Overflow behavior: truncate menu labels when width is constrained
-
-Do not implement one-off absolute positioning per component. Reuse the shared `PopoverWrapper` contract for `Select`, `PhoneInput`, `DateTimePicker`, and future menu triggers.
-
-### Rule 11: Accessibility guardrails and CI gates
-Every contribution must preserve accessibility contracts:
-- For custom-role widgets (`menuitem`, `switch`, `checkbox`, `radio`, `slider`, `tab`, `gridcell`), add/maintain at least one keyboard interaction test.
-- Disabled components must not be focusable (`disabled` for native controls; otherwise `tabIndex={-1}` + `aria-disabled="true"`).
-- Nested interactive controls inside clickable rows must stop propagation so child actions do not trigger parent actions.
-- Focus rings must be implemented with `:focus-visible` (never `:focus` as the visible focus trigger).
-- Popup/dropdown tests must cover Arrow keys, Enter/Space selection, Escape close, and focus return to trigger.
-
-Storybook signal-quality policy:
-- Disabled/demo-only stories may use `parameters: { a11y: { disable: true } }` for intentional exceptions.
-- Keep a11y opt-outs story-scoped only; never disable at component meta/global level for interactive components.
-
-CI enforcement:
-- Run `npm run test:a11y:keyboard-widgets`.
-- Run `npm run test:a11y:stories:light`.
-- Run `npm run test:a11y:stories:dark`.
-
-### Rule 12: Icons — Lucide only
-The only permitted icon library is `lucide-react`. Never use browser/OS-native icons, emoji, or any other icon library anywhere in the component library.
-
-```typescript
-// CORRECT
-import { ArrowUpDown, X, Check } from 'lucide-react';
-
-// WRONG
-// Any icon not from lucide-react
-// System/OS native icons (e.g. ↕ ⬆ ⬇)
-// Emoji used as icons
-```
-
-### Rule 13: Placeholder content — never leave it in place
-Component slots for icons, help text, and hint icons must never ship with placeholder values.
-Either populate with real, meaningful content or hide the slot entirely.
-
-- **Icons** → replace with a relevant Lucide icon, or omit the slot
-- **Help text** → replace with genuinely useful guidance, or omit
-- **Hint icons** → replace with meaningful tooltip content, or omit
-
-### Rule 14: Form behavior
-- Every form field is **mandatory by default**. Never use a red asterisk to mark required fields.
-- Only mark optional fields, using an `"Optional"` label in `var(--text-tertiary)` placed inline after the label text.
-- The primary submit CTA must be **disabled** until all mandatory fields contain a value.
-- Validate all fields on submit only — not in real time as the user types.
-  - Exceptions: password strength, character count limits, search/filter fields, OTP.
-- The primary submit button must always display the `⌘↵` shortcut using the `Shortcut` component.
-
-```tsx
-// CORRECT — optional field
-<label>Team <span style={{ color: 'var(--text-tertiary)' }}>Optional</span></label>
-
-// CORRECT — primary submit button
-<Button variant="primary">Add user <Shortcut>⌘↵</Shortcut></Button>
-
-// WRONG
-<label>First name *</label>   // never use asterisk
-```
-
----
-
-## Accessibility Requirements
-
-- WCAG AA minimum: 4.5:1 contrast for normal text, 3:1 for large text
-- All interactive elements must be keyboard operable
-- Focus order must follow logical reading order (top to bottom, left to right)
-- Colour alone must never convey meaning — pair with text, icon, or pattern
-- Every form input must have an associated `<label>` (visible or `aria-label`)
-- All inputs carry `aria-required="true"` by default. Optional fields omit `aria-required` or set it to `false`. Never use a visual asterisk.
-- Loading states must use `aria-busy="true"` and a descriptive `aria-label`
-- Disabled elements must NOT be focusable (use `disabled` attribute on native elements, `tabIndex={-1}` + `aria-disabled="true"` on custom elements)
-- Closed disclosure components (Accordion, Popover, Dropdown) must not expose their children to keyboard focus until open
-
----
-
-## Common Mistakes to Avoid
-
-1. **Using primitive tokens in components.** `var(--primitive-neutral-900)` in a component style is wrong. Use `var(--color-text-primary)`.
-2. **Using `:focus` instead of `:focus-visible`.** Always `:focus-visible`.
-3. **Hardcoding hex values or pixel sizes.** Everything comes from tokens.
-4. **Accepting `state` as a prop.** States are pseudo-classes + boolean props, not a state prop.
-5. **Omitting aria attributes.** Always add ARIA from the component docs.
-6. **Not exporting from `index.ts`.** Every component needs `export { X } from './X'` in its own index.ts, and re-exported from `src/index.ts`.
-7. **Using opacity for disabled state.** Use explicit disabled tokens (`--background-disabled`, `--color-text-disabled`). Never `opacity: 0.5`.
-8. **Passing styled props directly to DOM.** Always use transient props (`$propName`) in Styled Components to prevent DOM attribute forwarding.
-9. **Using asterisks for required fields.** Every field is mandatory by default. Only mark optional fields with an `"Optional"` label in `var(--text-tertiary)`.
-10. **Leaving placeholder icons, help text, or hint icons in components.** Replace with real content or hide the slot entirely.
-11. **Using icons from any library other than Lucide.** Only `lucide-react` is permitted. No system icons, no emoji, no other libraries.
-12. **Hardcoding horizontal padding instead of `var(--page-margin-x)`.** All horizontal container spacing must use this token.
-13. **Enabling the primary CTA before all mandatory fields have a value.** The submit button must be disabled until the form is fillable.
-14. **Omitting `⌘↵` from the primary form submit button.** Always include the `Shortcut` component on the primary CTA.
-15. **Using dataviz colors from generic semantic tokens or hardcoded hex.** Always use `--color-dataviz-*` tokens for all chart and graph colors.
-16. **Adding spacing overrides directly to components.** Never add `padding`, `margin`, `gap`, or any spacing property directly on a DS-Nagarro component element. All components have their internal spacing built in. To space components relative to each other, apply `--space-*` tokens only to wrapper or container elements.
-
----
-
-## Before Starting Each Component
-
-1. Read the component's doc file in `docs/`
-2. Identify all Figma variants → TypeScript props
-3. Identify all tokens needed (colour, typography, spacing, sizing)
-4. Implement component → stories → tests in that order
-5. Export from component `index.ts` and from `src/index.ts`
-
----
-
-*Source of truth for building DS-Nagarro components. Last updated: 2026-03-16.*

package/CLAUDE.md

@@ -1,6 +0,0 @@
-# DS-Nagarro — Claude Code entry point
-
-> **Read `AGENTS.md`** in this directory for all rules, structure, and component generation instructions.
-> **Read `AI.md`** for component usage specs, layout rules, and navigation patterns.
->
-> Do not treat this file as a source of rules — the two files above are the single sources of truth.