@bpfdev/oly-ui 1.0.1

package/README.md

@@ -0,0 +1,371 @@
+# @bpfdev/oly-ui
+
+> **npm:** [@bpfdev/oly-ui](https://www.npmjs.com/package/@bpfdev/oly-ui) · **private** (requires membership of the `@bpfdev/oly-ui` npm org)
+
+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 @bpfdev/oly-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 '@bpfdev/oly-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 '@bpfdev/oly-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 '@bpfdev/oly-ui';
+import type { FalconMultiSelectOption } from '@bpfdev/oly-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 '@bpfdev/oly-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 '@bpfdev/oly-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 '@bpfdev/oly-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 '@bpfdev/oly-ui';
+
+<FalconGrayButton onClick={handleCancel}>Cancel</FalconGrayButton>;
+```
+
+---
+
+### ButtonWithIcon
+
+A button that places an icon alongside a label.
+
+```tsx
+import { ButtonWithIcon } from '@bpfdev/oly-ui';
+
+<ButtonWithIcon icon={<AddIcon />} label="Add Item" onClick={handleAdd} />;
+```
+
+---
+
+### FalconSingleSwitch
+
+A labeled toggle switch.
+
+```tsx
+import { FalconSingleSwitch } from '@bpfdev/oly-ui';
+
+<FalconSingleSwitch
+  label="Enable notifications"
+  checked={enabled}
+  onChange={setEnabled}
+/>;
+```
+
+---
+
+### FalconDIstrictFilter
+
+A district-level filter selector.
+
+```tsx
+import { FalconDIstrictFilter } from '@bpfdev/oly-ui';
+import type { FalconDIstrictFilterOption } from '@bpfdev/oly-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 '@bpfdev/oly-ui';
+```
+
+---
+
+### AdvancedFiltersDialog
+
+A modal dialog for composing multi-criteria filter rules.
+
+```tsx
+import { AdvancedFiltersDialog } from '@bpfdev/oly-ui';
+```
+
+---
+
+### HeatMapChartLegend
+
+A color-scale legend for heat map charts.
+
+```tsx
+import { HeatMapChartLegend } from '@bpfdev/oly-ui';
+import type { HeatMapLegendItem } from '@bpfdev/oly-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 '@bpfdev/oly-ui';
+
+<ProgressBarNumber value={72} max={100} label="Completion" />;
+```
+
+---
+
+### AddCommentInput
+
+A text input designed for threaded comment submissions.
+
+```tsx
+import { AddCommentInput } from '@bpfdev/oly-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('@bpfdev/oly-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 © @bpfdev/oly-ui

package/dist/index.d.mts

@@ -0,0 +1,195 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ButtonProps, PaletteMode, Direction } from '@mui/material';
+import { ReactNode, ReactElement } from 'react';
+import { GridColDef } from '@mui/x-data-grid';
+
+interface AddCommentInputProps {
+    value: string;
+    setValue: (s: string) => void;
+    handleAddComment: () => void;
+    placeholder?: string;
+    buttonLabel?: string;
+}
+
+declare const AddCommentInput: ({ value, setValue, handleAddComment, placeholder, buttonLabel, }: AddCommentInputProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconMultiSelectOption {
+    id: number;
+    name: string;
+}
+interface FalconMultiSelectProps {
+    label: string;
+    /** Currently selected items (controlled) */
+    data: FalconMultiSelectOption[];
+    /** Callback when selection is applied or cleared */
+    setData: (value: FalconMultiSelectOption[]) => void;
+    /** Full list of options to choose from */
+    list: FalconMultiSelectOption[];
+}
+
+declare const FalconMultiSelect: ({ label, data, setData, list }: FalconMultiSelectProps) => react_jsx_runtime.JSX.Element;
+
+interface AdvancedFiltersDialogProps {
+    open: boolean;
+    onClose: () => void;
+    locationOptions?: FalconMultiSelectOption[];
+    businessAreaOptions?: FalconMultiSelectOption[];
+    selectedLocations?: FalconMultiSelectOption[];
+    selectedBusinessAreas?: FalconMultiSelectOption[];
+    onLocationsChange?: (value: FalconMultiSelectOption[]) => void;
+    onBusinessAreasChange?: (value: FalconMultiSelectOption[]) => void;
+    onApply?: () => void;
+    onCancel?: () => void;
+}
+
+declare const AdvancedFiltersDialog: ({ open, onClose, locationOptions, businessAreaOptions, selectedLocations, selectedBusinessAreas, onLocationsChange, onBusinessAreasChange, onApply, onCancel, }: AdvancedFiltersDialogProps) => react_jsx_runtime.JSX.Element;
+
+interface ButtonWithIconProps extends ButtonProps {
+    children: ReactNode;
+    icon?: ReactElement;
+}
+
+declare const ButtonWithIcon: ({ size, variant, children, icon, ...props }: ButtonWithIconProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconButtonProps extends ButtonProps {
+    loading?: boolean;
+    iconPlacement?: 'start' | 'end';
+}
+
+declare const FalconButton: ({ loading, disabled, children, size, variant, type, fullWidth, className, ...props }: FalconButtonProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconDIstrictFilterOption {
+    id: string | number;
+    label: string;
+}
+interface FalconDIstrictFilterProps {
+    label?: string;
+    options?: FalconDIstrictFilterOption[];
+    value?: FalconDIstrictFilterOption[];
+    onChange?: (value: FalconDIstrictFilterOption[]) => void;
+}
+
+/** District filter — full implementation can be migrated from apps/docs. */
+declare const FalconDIstrictFilter: ({ label, options, value, onChange, }: FalconDIstrictFilterProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconGrayButtonProps {
+    text: string;
+    Icon?: ReactNode;
+    onClick?: () => void;
+}
+
+declare const FalconGrayButton: ({ text, Icon, onClick, }: FalconGrayButtonProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconPaginationProps {
+    pageNo: number;
+    setPageNo: (n: number) => void;
+    perPage: number;
+    setPerPage: (n: number) => void;
+    totalItems: number;
+    perPageOptions?: number[];
+}
+
+declare const FalconPagination: ({ pageNo, setPageNo, perPage, setPerPage, totalItems, perPageOptions, }: FalconPaginationProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconSelectOption {
+    value: string;
+    label: string;
+}
+interface FalconSelectProps {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    options: string[] | FalconSelectOption[];
+    disabled?: boolean;
+    clearable?: boolean;
+}
+
+declare const FalconSelect: ({ label, value, onChange, options, disabled, clearable, }: FalconSelectProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconSingleSwitchProps {
+    color?: 'success' | 'warning' | 'error' | 'info' | 'primary' | 'secondary' | 'default';
+    setStatus?: (status: boolean) => void;
+    value?: boolean;
+    onChange?: (event: React.ChangeEvent<HTMLInputElement>, checked: boolean) => void;
+}
+
+declare const FalconSingleSwitch: ({ color, setStatus, value, onChange, }: FalconSingleSwitchProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconTableProps<T = Record<string, unknown>> {
+    rows: T[];
+    getRowId: (row: T) => string | number;
+    columns: GridColDef[];
+    pageSizeOptions?: number[];
+    initialState?: {
+        pagination?: {
+            paginationModel: {
+                pageSize: number;
+            };
+        };
+    };
+}
+
+declare const FalconTable: <T extends Record<string, unknown>>({ rows, getRowId, columns, pageSizeOptions, }: FalconTableProps<T>) => react_jsx_runtime.JSX.Element;
+
+interface FalconTicketColumsFilterProps {
+    columns?: {
+        id: string;
+        label: string;
+    }[];
+    selected?: string[];
+    onSelectionChange?: (selected: string[]) => void;
+}
+
+/** Column filter UI — full implementation can be migrated from apps/docs. */
+declare const FalconTicketColumsFilter: ({ columns, selected, onSelectionChange, }: FalconTicketColumsFilterProps) => react_jsx_runtime.JSX.Element;
+
+interface FalconTicketFilterProps {
+    children: ReactNode;
+    label?: string;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+
+declare const FalconTicketFilter: ({ children, label, open: controlledOpen, onOpenChange, }: FalconTicketFilterProps) => react_jsx_runtime.JSX.Element;
+
+interface HeatMapLegendItem {
+    label: string;
+    color: string;
+}
+interface HeatMapChartLegendProps {
+    title: string;
+    items: HeatMapLegendItem[];
+    gradientId: string;
+    gradientStops: {
+        offset: string;
+        color: string;
+    }[];
+}
+
+declare const HeatMapChartLegend: ({ title, items, gradientId, gradientStops, }: HeatMapChartLegendProps) => react_jsx_runtime.JSX.Element;
+
+interface ProgressBarNumberProps {
+    number: number;
+    progress: 0 | 50 | 100;
+    numColor: string;
+}
+
+declare const ProgressBarNumber: ({ number, progress, numColor, }: ProgressBarNumberProps) => react_jsx_runtime.JSX.Element;
+
+type Settings = {
+    mode: PaletteMode;
+    direction: Direction;
+    navHidden?: boolean;
+    appBarBlur: boolean;
+    navCollapsed: boolean;
+    layout?: 'vertical' | 'horizontal';
+    lastLayout?: 'vertical' | 'horizontal';
+};
+
+interface Props {
+    settings: Settings;
+    children: ReactNode;
+}
+declare const ThemeComponent: (props: Props) => react_jsx_runtime.JSX.Element;
+
+export { AddCommentInput, type AddCommentInputProps, AdvancedFiltersDialog, type AdvancedFiltersDialogProps, ButtonWithIcon, type ButtonWithIconProps, FalconButton, type FalconButtonProps, FalconDIstrictFilter, type FalconDIstrictFilterOption, type FalconDIstrictFilterProps, FalconGrayButton, type FalconGrayButtonProps, FalconMultiSelect, type FalconMultiSelectOption, type FalconMultiSelectProps, FalconPagination, type FalconPaginationProps, FalconSelect, type FalconSelectOption, type FalconSelectProps, FalconSingleSwitch, type FalconSingleSwitchProps, FalconTable, type FalconTableProps, ThemeComponent as FalconThemeProvider, FalconTicketColumsFilter, type FalconTicketColumsFilterProps, FalconTicketFilter, type FalconTicketFilterProps, HeatMapChartLegend, type HeatMapChartLegendProps, type HeatMapLegendItem, ProgressBarNumber, type ProgressBarNumberProps };