npm package: @qridwan/falcon-ui
Description: Falcon Oly Design System — React component library
Author: qridwan
Latest version: 1.0.1

# @qridwan/falcon-ui

A production-ready React component library built on top of [MUI](https://mui.com/), designed for data-heavy dashboards and enterprise UIs. Ships with full TypeScript types, tree-shakeable ESM + CJS bundles, and an optional Tailwind CSS preset.

---

## Installation

```bash
npm install @qridwan/falcon-ui
```

### Peer dependencies

The following packages must be installed in your project:

```bash
npm install react react-dom \
  @mui/material @mui/icons-material @mui/x-data-grid @mui/utils \
  @emotion/react @emotion/styled \
  @iconify/react
```

---

## Quick start

Wrap your application (or Storybook preview) with `FalconThemeProvider` to apply the Falcon design tokens:

```tsx
import { FalconThemeProvider } from '@qridwan/falcon-ui';

function App() {
  return (
    <FalconThemeProvider
      settings={{
        mode: 'light',
        direction: 'ltr',
        appBarBlur: true,
        navCollapsed: false,
      }}
    >
      {/* your app */}
    </FalconThemeProvider>
  );
}
```

---

## Components

### FalconButton

A MUI `Button` wrapper with a built-in loading state.

```tsx
import { FalconButton } from '@qridwan/falcon-ui';

<FalconButton variant="contained" loading={isSubmitting} onClick={handleSave}>
  Save
</FalconButton>;
```

| Prop        | Type                                  | Default       | Description                             |
| ----------- | ------------------------------------- | ------------- | --------------------------------------- |
| `variant`   | `'contained' \| 'outlined' \| 'text'` | `'contained'` | MUI button variant                      |
| `size`      | `'small' \| 'medium' \| 'large'`      | `'large'`     | Button size                             |
| `loading`   | `boolean`                             | `false`       | Shows a spinner and disables the button |
| `disabled`  | `boolean`                             | —             | Disables the button                     |
| `fullWidth` | `boolean`                             | `true`        | Stretches to container width            |
| `type`      | `'submit' \| 'button' \| 'reset'`     | `'submit'`    | HTML button type                        |

---

### FalconMultiSelect

A controlled multi-select autocomplete with apply/clear actions.

```tsx
import { FalconMultiSelect } from '@qridwan/falcon-ui';
import type { FalconMultiSelectOption } from '@qridwan/falcon-ui';

const regions: FalconMultiSelectOption[] = [
  { id: 1, name: 'North' },
  { id: 2, name: 'South' },
  { id: 3, name: 'East' },
];

function Example() {
  const [selected, setSelected] = React.useState<FalconMultiSelectOption[]>([]);

  return (
    <FalconMultiSelect
      label="Region"
      list={regions}
      data={selected}
      setData={setSelected}
    />
  );
}
```

| Prop      | Type                                         | Description                             |
| --------- | -------------------------------------------- | --------------------------------------- |
| `label`   | `string`                                     | Placeholder / trigger label             |
| `list`    | `FalconMultiSelectOption[]`                  | All available options                   |
| `data`    | `FalconMultiSelectOption[]`                  | Currently selected options (controlled) |
| `setData` | `(value: FalconMultiSelectOption[]) => void` | Called when Apply or Clear is clicked   |

---

### FalconSelect

A single-value select built on MUI `TextField`.

```tsx
import { FalconSelect } from '@qridwan/falcon-ui';

<FalconSelect
  label="Status"
  value={status}
  onChange={setStatus}
  options={['Active', 'Inactive', 'Pending']}
  clearable
/>;
```

| Prop        | Type                               | Default | Description                 |
| ----------- | ---------------------------------- | ------- | --------------------------- |
| `label`     | `string`                           | —       | Field label                 |
| `value`     | `string`                           | —       | Selected value (controlled) |
| `onChange`  | `(value: string) => void`          | —       | Change callback             |
| `options`   | `string[] \| FalconSelectOption[]` | —       | Options list                |
| `disabled`  | `boolean`                          | `false` | Disables the field          |
| `clearable` | `boolean`                          | `false` | Adds a clear button         |

---

### FalconPagination

A combined page-number + page-size selector.

```tsx
import { FalconPagination } from '@qridwan/falcon-ui';

<FalconPagination
  pageNo={page}
  setPageNo={setPage}
  perPage={rowsPerPage}
  setPerPage={setRowsPerPage}
  totalItems={totalCount}
  perPageOptions={[10, 25, 50]}
/>;
```

| Prop             | Type                  | Default        | Description                   |
| ---------------- | --------------------- | -------------- | ----------------------------- |
| `pageNo`         | `number`              | —              | Current page (1-based)        |
| `setPageNo`      | `(n: number) => void` | —              | Page change callback          |
| `perPage`        | `number`              | —              | Rows per page                 |
| `setPerPage`     | `(n: number) => void` | —              | Rows-per-page change callback |
| `totalItems`     | `number`              | —              | Total record count            |
| `perPageOptions` | `number[]`            | `[10, 25, 50]` | Dropdown options              |

---

### FalconTable

A thin wrapper around MUI X DataGrid with sensible defaults.

```tsx
import { FalconTable } from '@qridwan/falcon-ui';
import type { GridColDef } from '@mui/x-data-grid';

const columns: GridColDef[] = [
  { field: 'id', headerName: 'ID', width: 90 },
  { field: 'name', headerName: 'Name', flex: 1 },
];

<FalconTable
  rows={data}
  columns={columns}
  getRowId={row => row.id}
  pageSizeOptions={[10, 25]}
  initialState={{ pagination: { paginationModel: { pageSize: 10 } } }}
/>;
```

| Prop              | Type                           | Description                |
| ----------------- | ------------------------------ | -------------------------- |
| `rows`            | `T[]`                          | Row data array             |
| `columns`         | `GridColDef[]`                 | Column definitions         |
| `getRowId`        | `(row: T) => string \| number` | Row identity function      |
| `pageSizeOptions` | `number[]`                     | Page size options          |
| `initialState`    | `object`                       | MUI DataGrid initial state |

---

### FalconGrayButton

A secondary action button styled with a gray palette.

```tsx
import { FalconGrayButton } from '@qridwan/falcon-ui';

<FalconGrayButton onClick={handleCancel}>Cancel</FalconGrayButton>;
```

---

### ButtonWithIcon

A button that places an icon alongside a label.

```tsx
import { ButtonWithIcon } from '@qridwan/falcon-ui';

<ButtonWithIcon icon={<AddIcon />} label="Add Item" onClick={handleAdd} />;
```

---

### FalconSingleSwitch

A labeled toggle switch.

```tsx
import { FalconSingleSwitch } from '@qridwan/falcon-ui';

<FalconSingleSwitch
  label="Enable notifications"
  checked={enabled}
  onChange={setEnabled}
/>;
```

---

### FalconDIstrictFilter

A district-level filter selector.

```tsx
import { FalconDIstrictFilter } from '@qridwan/falcon-ui';
import type { FalconDIstrictFilterOption } from '@qridwan/falcon-ui';

const districts: FalconDIstrictFilterOption[] = [
  { id: 1, name: 'Downtown' },
  { id: 2, name: 'Uptown' },
];

<FalconDIstrictFilter list={districts} data={selected} setData={setSelected} />;
```

---

### FalconTicketFilter / FalconTicketColumsFilter

Ticket management filters for status, priority, and column visibility toggles.

```tsx
import {
  FalconTicketFilter,
  FalconTicketColumsFilter,
} from '@qridwan/falcon-ui';
```

---

### AdvancedFiltersDialog

A modal dialog for composing multi-criteria filter rules.

```tsx
import { AdvancedFiltersDialog } from '@qridwan/falcon-ui';
```

---

### HeatMapChartLegend

A color-scale legend for heat map charts.

```tsx
import { HeatMapChartLegend } from '@qridwan/falcon-ui';
import type { HeatMapLegendItem } from '@qridwan/falcon-ui';

const items: HeatMapLegendItem[] = [
  { color: '#f7f7f7', label: 'Low' },
  { color: '#EE8B3A', label: 'High' },
];

<HeatMapChartLegend items={items} />;
```

---

### ProgressBarNumber

A numeric value displayed alongside a progress bar.

```tsx
import { ProgressBarNumber } from '@qridwan/falcon-ui';

<ProgressBarNumber value={72} max={100} label="Completion" />;
```

---

### AddCommentInput

A text input designed for threaded comment submissions.

```tsx
import { AddCommentInput } from '@qridwan/falcon-ui';

<AddCommentInput onSubmit={text => postComment(text)} />;
```

---

## Tailwind CSS preset

If you use Tailwind, extend your config with the Falcon color tokens:

```js
// tailwind.config.js
module.exports = {
  presets: [require('@qridwan/falcon-ui/tailwind.preset')],
  // ...
};
```

This exposes Falcon's primary palette as `falcon-*` utility classes (e.g. `bg-falcon-500`).

> **Note:** The preset reads from the built `dist/` folder — run `npm run build` in the package before using the preset in a fresh clone.

---

## FalconThemeProvider settings

| Prop           | Type                | Default   | Description                  |
| -------------- | ------------------- | --------- | ---------------------------- |
| `mode`         | `'light' \| 'dark'` | `'light'` | Color scheme                 |
| `direction`    | `'ltr' \| 'rtl'`    | `'ltr'`   | Text direction               |
| `appBarBlur`   | `boolean`           | `true`    | Frosted-glass app bar effect |
| `navCollapsed` | `boolean`           | `false`   | Collapsed sidebar state      |

---

## Development

```bash
# build once
npm run build

# watch mode
npm run dev

# run tests
npm run test

# type-check without emitting
npm run typecheck
```

---

## License

MIT © qridwan