# കാർഡ്

> ബന്ധപ്പെട്ട ഉള്ളടക്കം ഗ്രൂപ്പ് ചെയ്യുന്ന ഒരു സർഫേസ്, ഹെഡർ, ബോഡി, ഫൂട്ടർ എന്നിവയോടെ, കൂടാതെ ഒരൊറ്റ കണക്കും അതിന്റെ ട്രെൻഡും കാണിക്കാൻ Stat.

GramproKit 2.0.0-beta · General · ബീറ്റ (പരീക്ഷണാത്മകം; API-കൾ മാറാം) · ഉറവിടം: https://gramprokit.vercel.app/ml/card

## ഇൻസ്റ്റലേഷൻ

```bash
npx gbs-add-block@latest -a Card -beta
```

എല്ലാ കമ്പോണന്റുകളും ഇംപോർട്ട് ചെയ്യുന്ന ചെറിയ `shared` ഫോൾഡറിനൊപ്പം, `card` ഫോൾഡർ ഈ ബ്ലോക്ക് നിങ്ങളുടെ പ്രോജക്ടിലേക്ക് കോപ്പി ചെയ്യുന്നു. കോഡ് നിങ്ങളുടേതാണ്, സ്വതന്ത്രമായി മാറ്റം വരുത്താം.
React അല്ലാതെ **peer dependencies** ഒന്നും ഇല്ല.

**ആവശ്യകതകൾ**

- React 19-ഉം `@types/react` 19-ഉം
- TypeScript ടാർഗെറ്റ് ES2022 അല്ലെങ്കിൽ അതിനു ശേഷമുള്ളത്, `"jsx": "react-jsx"` എന്നതോടെ
- 2024-നു ശേഷമുള്ള ബ്രൗസറുകൾ (സ്റ്റൈലുകൾ `light-dark()`, `color-mix()` ഉപയോഗിക്കുന്നു)

സ്റ്റൈൽഷീറ്റ് ഒരു തവണ ഇംപോർട്ട് ചെയ്യുക, ഉദാഹരണത്തിന് നിങ്ങളുടെ ഗ്ലോബൽ CSS-ൽ:

```css
@import "../components/card/styles.css";
```

അല്ലെങ്കിൽ നിങ്ങളുടെ റൂട്ട് ലേഔട്ട് / എൻട്രി ഫയലിൽ:

```ts
import "@/components/card/styles.css";
```

പരസ്പരം ബന്ധപ്പെട്ടവയെ ഒരു കാർഡ് ഗ്രൂപ്പ് ചെയ്യുകയും അവയ്ക്ക് ഒരു എഡ്ജ് നൽകുകയും ചെയ്യുന്നു. ഡാഷ്ബോർഡിന്റെ മറുപകുതിയാണ് `Stat`: ഒരു കണക്ക്, അതിന്റെ ലേബൽ, അത് എങ്ങനെ മാറിയിരിക്കുന്നു എന്നത്.

> **ശ്രദ്ധിക്കുക:** എല്ലാ കമ്പോണന്റുകളും ഒരുമിച്ച് തീം ചെയ്യാൻ :root-ൽ --gbs-* വേരിയബിളുകൾ സെറ്റ് ചെയ്യുക, ഗ്രിഡ് ഉൾപ്പെടെ. ഓരോ കമ്പോണന്റിന്റെയും സ്വന്തം വേരിയബിളുകൾ ഇവയിലേക്കും, പിന്നീട് ബിൽറ്റ്-ഇൻ പാലറ്റിലേക്കും ഫാൾബാക്ക് ചെയ്യുന്നു, അതിനാൽ ഡിഫോൾട്ടായി കമ്പോണന്റുകൾ ഒരേ പോലെ കാണപ്പെടുന്നു.

#### ഡിഫോൾട്ട്

_ഇന്ററാക്ടീവ് ഡെമോ:_ [തത്സമയ ഉദാഹരണം കാണുക](https://gramprokit.vercel.app/ml/card)

## ക്വിക്ക് സ്റ്റാർട്ട്

```tsx
import {
  Card,
  CardHeader,
  CardBody,
  CardFooter,
  Stat,
  trendDirection,
} from "@/components/card";
import "@/components/card/styles.css";

<Card>
  <CardHeader
    title={<h3>Revenue</h3>}
    description="Billed this month"
    actions={
      <Menu
        trigger={
          <Button variant="ghost" size="sm">
            Options
          </Button>
        }
      >
        …
      </Menu>
    }
  />
  <CardBody>
    <Stat
      label="This month"
      value="£48,120"
      trend={{
        direction: trendDirection(12.4),
        label: "12.4%",
        description: "vs last month",
      }}
    />
  </CardBody>
  <CardFooter>
    <Button variant="ghost" size="sm">
      View invoices
    </Button>
  </CardFooter>
</Card>;
```

## പ്രോപ്സ് ടേബിൾ

#### Card

| Prop                               | Type                                  | Default    | Description                                                                        |
| ---------------------------------- | ------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| `variant`                          | `"outlined" \| "elevated" \| "plain"` | `outlined` | എഡ്ജ് എങ്ങനെ വരയ്ക്കുന്നു.                                                         |
| `padding`                          | `"none" \| "sm" \| "md" \| "lg"`      | `md`       | ഹെഡർ, ബോഡി, ഫൂട്ടർ എന്നിവയ്ക്ക് ബാധകം.                                             |
| `href`, `target`, `rel`            | `string`                              | —          | മുഴുവൻ കാർഡിനെയും ഒരു ലിങ്കാക്കുന്നു.                                              |
| `interactive`                      | `boolean`                             | `false`    | മറ്റൊരു വിധത്തിൽ ക്ലിക്ക് ചെയ്യാവുന്ന ഒരു കാർഡിനുള്ള ഹോവർ, ഫോക്കസ് സ്റ്റൈലുകൾ.     |
| `className`, `classNames`, `style` | —                                     | —          | സ്ലോട്ടുകൾ: `root`, `header`, `title`, `description`, `actions`, `body`, `footer`. |
| `ref`                              | `Ref<HTMLElement>`                    | —          | റൂട്ട് എലമെന്റ്.                                                                   |

`CardHeader`-ന് `title`, `description`, `actions`, ചിൽഡ്രൻ എന്നിവ ലഭിക്കുന്നു. `CardBody`-ക്കും `CardFooter`-നും ചിൽഡ്രനും ഒരു `className`-ഉം ലഭിക്കുന്നു.

#### Stat

| Prop                               | Type                                          | Description                                                    |
| ---------------------------------- | --------------------------------------------- | -------------------------------------------------------------- |
| `label`                            | `ReactNode`                                   | കണക്ക് എന്താണെന്ന്. എപ്പോഴും കാണിക്കുന്നു.                     |
| `value`                            | `ReactNode`                                   | ഇതിനകം ഫോർമാറ്റ് ചെയ്ത കണക്ക്.                                 |
| `trend`                            | `{ direction, label, invert?, description? }` | അത് എങ്ങനെ മാറിയിരിക്കുന്നു.                                   |
| `help`                             | `ReactNode`                                   | കണക്കിനു താഴെയുള്ള ഒരു കുറിപ്പ്.                               |
| `icon`                             | `ReactNode`                                   | ലേബലിനടുത്ത് വരച്ചത്.                                          |
| `loading`                          | `boolean`                                     | "Loading" എന്ന് അറിയിക്കപ്പെടുന്ന പ്ലേസ്‌ഹോൾഡർ ബാറുകൾ.         |
| `className`, `classNames`, `style` | —                                             | സ്ലോട്ടുകൾ: `root`, `label`, `value`, `trend`, `help`, `icon`. |

## ഹെഡിംഗുകൾ പേജിന്റേതാണ്

നിങ്ങൾക്കായി ഒരു ഹെഡിംഗ് ലെവൽ തിരഞ്ഞെടുക്കുന്നതിനു പകരം, നിങ്ങൾ എന്ത് നൽകുന്നോ അത് `title` ആയി `CardHeader` സ്വീകരിക്കുന്നു:

```tsx
<CardHeader title={<h3>Revenue</h3>} />
```

ഒരു കാർഡ് ഒരു പേജിലെ പ്രധാന കാര്യമോ, ഒരു ഗ്രിഡിലെ പന്ത്രണ്ട് ടൈലുകളിൽ ഒന്നോ ആകാം, കൂടാതെ ഓരോന്നിലും ശരിയായ ലെവൽ വ്യത്യസ്തമാണ്. നിങ്ങളുടെ സ്വന്തം എലമെന്റ് കൈമാറുന്നത് ഡോക്യുമെന്റ് ഔട്ട്‌ലൈൻ നിങ്ങളുടേതായി തന്നെ നിലനിർത്തുന്നു.

## നിറത്തെ ആശ്രയിക്കാതെയുള്ള ട്രെൻഡുകൾ

```tsx
<Stat
  label="Churn"
  value="2.1%"
  trend={{ direction: trendDirection(0.6), label: "0.6pp", invert: true }}
/>
```

താഴേക്കാണ് നല്ല ഫലം എന്നുള്ള കണക്കുകൾക്കാണ് `invert` — ചേൺ (churn), റീഫണ്ടുകൾ, പിശക് നിരക്കുകൾ, പേജ് ഭാരം. ഇത് നിറം മാത്രമേ മാറ്റുന്നുള്ളൂ: അമ്പടയാളം ഇപ്പോഴും സംഖ്യ നീങ്ങിയ ദിശ ചൂണ്ടിക്കാണിക്കുന്നു, കാരണം അമ്പടയാളം വസ്തുത അറിയിക്കുന്നു, നിറം വിലയിരുത്തലും.

ദിശ സ്ക്രീൻ റീഡറുകൾക്കായി എഴുതിയും കാണിക്കുന്നു ("Up", "Down", "No change"), അതിനാൽ അർത്ഥം ഒരിക്കലും നിറത്തിൽ മാത്രം ആശ്രയിക്കുന്നില്ല. `direction: "flat"`-ന് ഒരു നിറവും ലഭിക്കുന്നില്ല.

## ലിങ്കുകളായ കാർഡുകൾ

```tsx
<Card href="/invoices/1043">
  <CardBody>INV-1043 · £2,400</CardBody>
</Card>
```

`href`-നൊപ്പം കാർഡ് ഒരു `<a>` ആയി റെൻഡർ ചെയ്യുന്നു. മറ്റ് ലിങ്കുകളും ബട്ടണുകളും അതിൽ നിന്ന് അകറ്റി നിർത്തുക: ഇന്ററാക്ടീവ് എലമെന്റുകൾ നെസ്റ്റ് ചെയ്യുന്നത് അസാധുവായ HTML ആണ്, കൂടാതെ കീബോർഡിനെ കുഴപ്പത്തിലാക്കുന്നു. ഒരു കാർഡിന് ഒരു പ്രധാന ലിങ്കും അതിന്റേതായ ബട്ടണുകളും വേണ്ടിവരുമ്പോൾ, നിങ്ങളുടെ സ്വന്തം ഹാൻഡ്‌ലറോടെ `interactive` ഉപയോഗിക്കുക, അല്ലെങ്കിൽ ലിങ്ക് ടൈറ്റിലിൽ വെക്കുക.

## സ്റ്റൈലിംഗും തീമിംഗും

എല്ലാ റൂളുകളും CSS `components` ലെയറിലാണ്, അതിനാൽ `className` / `classNames` വഴി കടന്നുപോകുന്ന യൂട്ടിലിറ്റി ക്ലാസുകൾ അവയെ ഓവർറൈഡ് ചെയ്യുന്നു.

#### CSS വേരിയബിളുകൾ

| Variable                                       | Used for                                               |
| ---------------------------------------------- | ------------------------------------------------------ |
| `--cd-bg`, `--cd-fg`                           | കാർഡ് സർഫേസും ടെക്സ്റ്റും.                             |
| `--cd-muted`                                   | വിവരണങ്ങൾ, ലേബലുകൾ, ഹെൽപ്പ് ടെക്സ്റ്റ്.                |
| `--cd-border`                                  | ഔട്ട്‌ലൈനും ഫൂട്ടർ റൂളും.                              |
| `--cd-hover`                                   | ഇന്ററാക്ടീവ് കാർഡുകൾ, കൂടാതെ Stat പ്ലേസ്‌ഹോൾഡർ ബാറുകൾ. |
| `--cd-focus`                                   | ഒരു ഇന്ററാക്ടീവ് കാർഡിലെ ഫോക്കസ് റിംഗ്.                |
| `--cd-success`, `--cd-danger`                  | ട്രെൻഡ് നിറങ്ങൾ.                                       |
| `--cd-shadow`, `--cd-radius`, `--cd-font-size` | കാർഡിന്റെ ആകൃതി.                                       |
| `--cd-px`                                      | `padding` പ്രോപ്പ് സെറ്റ് ചെയ്യുന്ന പാഡിംഗ്.           |

`.cd-root`-ലോ, `:root`-ലോ, അല്ലെങ്കിൽ `style`-ലൂടെയോ ഇവ ഓവർറൈഡ് ചെയ്യുക. ഓരോ വേരിയബിളും അതേ പേരിലുള്ള ഷെയേർഡ് `--gbs-*`-ലേക്ക് ഫാൾബാക്ക് ചെയ്യുന്നു, പിന്നീട് ആ സ്റ്റൈൽഷീറ്റ് ലോഡ് ചെയ്തിട്ടുണ്ടെങ്കിൽ DataGrid-ന്റെ `--dg-*`-ലേക്കും, അവസാനം ബിൽറ്റ്-ഇൻ പാലറ്റിലേക്കും.

#### ഡാറ്റ ആട്രിബ്യൂട്ടുകൾ

| Element             | Attributes                                         |
| ------------------- | -------------------------------------------------- |
| Root (`.cd-root`)   | `data-variant`, `data-padding`, `data-interactive` |
| Stat (`.st-root`)   | `data-loading`                                     |
| Trend (`.st-trend`) | `data-direction`, `data-positive`                  |

## ഹെഡ്‌ലെസ് ഉപയോഗം

`core/trend.ts` ഫ്രെയിംവർക്ക്-രഹിതമാണ്:

```ts
import { trendDirection, isPositive, percentChange } from "@/components/card";

trendDirection(12.4); // "up"
trendDirection(0.4, 0.5); // "flat" — under the threshold
isPositive("down", true); // true  — down is good for churn
percentChange(200, 250); // 25
percentChange(0, 10); // null — growth from zero is not a percentage
```

## Next.js

`Card`-ഉം `Stat`-ഉം ഇവന്റ് ഹാൻഡ്‌ലറുകളും ref-കളും സ്വീകരിക്കുന്നതിനാൽ `"use client"` എന്ന് അടയാളപ്പെടുത്തിയിരിക്കുന്നു. അവയെ ഒരു സെർവർ കമ്പോണന്റിൽ നിന്ന് റെൻഡർ ചെയ്യുന്നത് നിങ്ങളെ ഒന്നും തടയുന്നില്ല — ഡാറ്റ പ്രോപ്‌സായി കൈമാറുക.

#### കുറിപ്പുകൾ

- എലവേഷൻ തന്ത്രങ്ങൾ ഒന്നുമില്ലാത്ത ഒരു ലളിതമായ സർഫേസ് ആണ് കാർഡ്: ഒരു ബോർഡർ, ഒരു ഓപ്ഷണൽ ഷാഡോ.
- `Stat`-ന്റെ കണക്കുകൾ ടാബുലാർ അക്കങ്ങൾ (tabular numerals) ഉപയോഗിക്കുന്നു, അതിനാൽ അവയുടെ ഒരു കോളം വരിവരിയായി വരുന്നു.