@ztwoint/z-ui 0.1.139 → 0.1.141

package/dist/components/kpi-card/kpi-card.d.ts

@@ -1,11 +1,11 @@
-import * as React from 'react';
+import { ReactNode } from 'react';
 declare const kpiCardVariants: (props?: ({
     active?: boolean | null | undefined;
 } & import('class-variance-authority/dist/types').ClassProp) | undefined) => string;
 export interface KpiCardProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'title'> {
     titleText?: string;
     subtitleText?: string;
-    bottomText?: string;
+    bottomText?: string | ReactNode;
     /** Whether the card is in an active/selected state */
     active?: boolean;
     /** React node to render in the top-right corner (e.g., action buttons) */
@@ -13,5 +13,5 @@ export interface KpiCardProps extends Omit<React.ButtonHTMLAttributes<HTMLButton
     /** React node to render in the bottom-right corner (e.g., an icon) */
     bottomRightIcon?: React.ReactNode;
 }
-declare const KpiCard: React.ForwardRefExoticComponent<KpiCardProps & React.RefAttributes<HTMLButtonElement>>;
+declare const KpiCard: import('react').ForwardRefExoticComponent<KpiCardProps & import('react').RefAttributes<HTMLButtonElement>>;
 export { KpiCard, kpiCardVariants };

package/dist/components/kpi-card/kpi-card.js

@@ -1,8 +1,8 @@
 import { jsxs as r, jsx as e } from "react/jsx-runtime";
-import * as m from "react";
-import { cva as p } from "class-variance-authority";
+import { cva as m } from "class-variance-authority";
+import { forwardRef as p } from "react";
 import { cn as f } from "../../lib/utils.js";
-const x = p(
+const x = m(
   [
     "flex flex-col gap-2 items-start overflow-clip text-left",
     "px-3.5 py-3.5 rounded-xl border border-stroke-solid-high",
@@ -22,7 +22,7 @@ const x = p(
       active: !1
     }
   }
-), u = m.forwardRef(
+), u = p(
   ({
     className: t,
     titleText: i = "Title Text",

package/dist/components/primitives/table-card/Architecture.md

@@ -0,0 +1,217 @@
+# TableCard Architecture
+
+## Purpose
+
+`TableCard` is a high-level composite component that orchestrates the `Table` and `Filter` components to provide a complete data display solution with:
+- Search functionality
+- Advanced filtering
+- Pagination with info and quick jumper
+- Configurable table body with sorting
+- Loading and error states
+- Customizable header and footer sections
+
+## File Structure
+
+```
+src/components/primitives/table-card/
+├── index.ts                 # Public exports
+├── table-card.tsx           # Main component implementation
+├── table-card.type.ts       # TypeScript interfaces
+├── table-card.stories.tsx   # Storybook stories
+└── Architecture.md          # This file
+```
+
+## Component Hierarchy
+
+```mermaid
+flowchart TD
+    TableCard["TableCard"]
+    
+    subgraph TableWrapper [Table Provider]
+        Table["Table"]
+        TableHeader["Table.Header"]
+        TableHeaderContent["Table.HeaderContent"]
+        TableSearch["Table.Search"]
+        TableBody["Table.Body"]
+        TableFooter["Table.Footer"]
+        TableFooterContent["Table.FooterContent"]
+        TablePagination["Table.Pagination"]
+        TablePaginationInfo["Table.PaginationInfo"]
+        TablePaginationQuickJumper["Table.PaginationQuickJumper"]
+    end
+    
+    subgraph FilterWrapper [Filter Provider]
+        Filter["Filter"]
+        FilterButton["Filter.FilterButton"]
+        FilterColumnButton["Filter.FilterColumnButton"]
+    end
+    
+    TableCard --> Table
+    Table --> TableHeader
+    TableHeader --> TableHeaderContent
+    TableHeaderContent --> TableSearch
+    TableHeaderContent --> Filter
+    Filter --> FilterButton
+    Filter --> FilterColumnButton
+    Table --> TableBody
+    Table --> TableFooter
+    TableFooter --> TableFooterContent
+    TableFooterContent --> TablePaginationInfo
+    TableFooterContent --> TablePaginationQuickJumper
+    TableFooterContent --> TablePagination
+```
+
+## Data Flow
+
+```mermaid
+flowchart LR
+    subgraph ExternalProps [External Props]
+        dataSource["dataSource"]
+        schema["schema"]
+        searchProps["search"]
+        filterProps["filter"]
+        paginationProps["pagination"]
+        bodyProps["body"]
+    end
+    
+    subgraph TableCard [TableCard Component]
+        renderLogic["Render Logic"]
+        errorState["Error State"]
+        loadingOverlay["Loading Overlay"]
+    end
+    
+    subgraph TableContext [Table Context]
+        tableData["dataSource, schema"]
+    end
+    
+    subgraph FilterContext [Filter Context]
+        filterData["filterSchema, filter values"]
+    end
+    
+    ExternalProps --> TableCard
+    TableCard --> TableContext
+    TableCard --> FilterContext
+    TableCard --> errorState
+    TableCard --> loadingOverlay
+```
+
+## Key Interfaces
+
+### TableCardProps
+
+```typescript
+interface TableCardProps {
+  // Core table props
+  dataSource: Record<string, unknown>[];
+  schema: TableSchema;
+
+  // Layout props
+  className?: string;
+  rounded?: boolean;
+  bordered?: boolean;
+
+  // Header section
+  showHeader?: boolean;
+  headerClassName?: string;
+  search?: Partial<TableSearch> & { className?: string };
+  filter?: Partial<TableFilter> & {
+    quickFilters?: string[];
+    showFilterButton?: boolean;
+    filterSchema: FilterSchema;
+    onFilterClick?: (filters: FilterRule[], selectedColumn: string) => void;
+  };
+  headerLeftContent?: React.ReactNode;
+  headerActions?: React.ReactNode;
+
+  // Body section
+  body?: {
+    cell?: TableProps['cell'];
+    sort?: TableSort;
+    className?: string;
+    stickyHeader?: boolean;
+  };
+
+  // Footer section
+  showFooter?: boolean;
+  footerClassName?: string;
+  pagination?: PaginationProps;
+  paginationInfo?: PaginationInfoProps;
+  paginationQuickJumper?: PaginationQuickJumperProps;
+
+  // State props
+  loading?: boolean;
+  emptyMessage?: string;
+  dataSourceError?: boolean | string;
+  error?: boolean | string;
+}
+```
+
+## Component Sections
+
+### 1. Error State
+When `error` prop is truthy, renders error UI instead of the table.
+
+### 2. Header Section
+Conditionally rendered when `showHeader=true` and has content:
+- `headerLeftContent` - Custom left content
+- `Table.Search` - Search input
+- `Filter` - Filter system with FilterButton and quick filter buttons
+- `headerActions` - Custom action buttons
+
+### 3. Body Section
+`Table.Body` renders the actual table with:
+- TableHeader (column headers with optional sorting)
+- TableRow (data rows)
+- Empty/Error message states
+
+### 4. Footer Section
+Conditionally rendered when `showFooter=true` and has content:
+- `Table.PaginationInfo` - "Showing X-Y of Z" text
+- `Table.PaginationQuickJumper` - Go to page input
+- `Table.Pagination` - Page navigation buttons
+
+### 5. Loading Overlay
+Absolute positioned overlay shown when `loading=true`.
+
+## Subcomponent Architecture References
+
+- **Table Component**: [src/components/table/Architecture.md](../../table/Architecture.md)
+- **Filter Component**: [src/components/table-filter/Architecture.md](../../table-filter/Architecture.md)
+
+## Usage Example
+
+```tsx
+<TableCard
+  dataSource={data}
+  schema={[
+    { key: 'name', title: 'Name', cellType: 'text' },
+    { key: 'amount', title: 'Amount', cellType: 'number' },
+  ]}
+  search={{
+    value: searchValue,
+    onChange: setSearchValue,
+    placeholder: 'Search...',
+  }}
+  filter={{
+    filterSchema: [
+      { filterKey: 'status', title: 'Status', type: 'checkbox', options: { Active: 10, Inactive: 5 } },
+    ],
+    value: filters,
+    onChange: setFilters,
+    quickFilters: ['status'],
+  }}
+  pagination={{
+    currentPage: 1,
+    totalPage: 10,
+    onChange: setPage,
+  }}
+  loading={isLoading}
+/>
+```
+
+## Dependencies
+
+- `Table` from `../../table`
+- `Filter` from `../../table-filter`
+- `cn` utility from `../../../lib`
+- `OctagonWarningCopy` icon for error state

package/dist/components/table/Architecture.md

@@ -0,0 +1,304 @@
+# Table Architecture
+
+## Purpose
+
+The `Table` component is a compound component that provides a flexible and composable table system. It uses React Context to share state between its sub-components and follows the compound component pattern for maximum flexibility.
+
+## File Structure
+
+```
+src/components/table/
+├── index.ts                    # Public exports
+├── table-provider.tsx          # Main provider and compound component setup
+├── table.tsx                   # TableBody implementation
+├── table.context.ts            # React Context definition
+├── table.type.ts               # TypeScript interfaces
+├── table.const.ts              # CSS classes and constants
+├── table.utils.ts              # Utility functions
+├── table.stories.tsx           # Storybook stories
+├── Architecture.md             # This file
+└── components/
+    ├── index.ts                # Component exports
+    ├── table-cell.tsx          # Individual cell renderer
+    ├── table-row.tsx           # Row renderer
+    ├── table-header-wrapper.tsx    # Header container
+    ├── table-header-content.tsx    # Header content wrapper
+    ├── table-footer.tsx        # Footer container
+    ├── table-footer-content.tsx    # Footer content wrapper
+    ├── table-message-state.tsx # Empty/Error state display
+    ├── table-loading-state.tsx # Loading state display
+    ├── table-header/           # Column header components
+    │   ├── index.ts
+    │   ├── table-header.tsx    # Column headers with sorting
+    │   ├── table-header.utils.ts
+    │   └── table-sort-icon.tsx
+    ├── table-search/           # Search component
+    │   ├── index.ts
+    │   └── table-search.tsx
+    ├── pagination/             # Pagination components
+    │   ├── index.ts
+    │   ├── pagination.tsx
+    │   ├── pagination.hook.ts
+    │   ├── pagination.type.ts
+    │   ├── pagination.const.ts
+    │   ├── pagination.utils.ts
+    │   └── components/
+    │       ├── index.ts
+    │       ├── pagination-info.tsx
+    │       ├── pagination-quick-jumper.tsx
+    │       └── pagination-quick-jumper.hook.ts
+    └── cell/                   # Cell type renderers
+        ├── index.ts
+        ├── number-cell.tsx
+        ├── boolean-cell.tsx
+        ├── link-cell.tsx
+        ├── avatar-cell.tsx
+        ├── label-cell.tsx
+        └── description-cell.tsx
+```
+
+## Component Hierarchy
+
+```mermaid
+flowchart TD
+    TableProvider["Table (TableProvider)"]
+    
+    subgraph CompoundComponents [Compound Components]
+        TableBody["Table.Body"]
+        TableHeader["Table.Header (wrapper)"]
+        TableHeaderContent["Table.HeaderContent"]
+        TableSearch["Table.Search"]
+        TableFooter["Table.Footer"]
+        TableFooterContent["Table.FooterContent"]
+        TablePagination["Table.Pagination"]
+        TablePaginationInfo["Table.PaginationInfo"]
+        TablePaginationQuickJumper["Table.PaginationQuickJumper"]
+    end
+    
+    subgraph BodyInternals [Table.Body Internals]
+        InternalHeader["TableHeader (columns)"]
+        TableRow["TableRow"]
+        TableCell["TableCell"]
+        TableMessageState["TableMessageState"]
+    end
+    
+    subgraph CellTypes [Cell Type Renderers]
+        NumberCell["NumberCell"]
+        BooleanCell["BooleanCell"]
+        LinkCell["LinkCell"]
+        AvatarCell["AvatarCell"]
+        LabelCell["LabelCell"]
+        DescriptionCell["DescriptionCell"]
+    end
+    
+    TableProvider --> CompoundComponents
+    TableBody --> BodyInternals
+    TableRow --> TableCell
+    TableCell --> CellTypes
+```
+
+## Compound Component Pattern
+
+The Table uses a compound component pattern where sub-components are attached to the main component:
+
+```typescript
+interface TableCompoundComponent extends React.FC<TableProviderProps> {
+  Body: typeof TableBody;
+  Search: typeof TableSearch;
+  Pagination: typeof Pagination;
+  PaginationInfo: typeof PaginationInfo;
+  PaginationQuickJumper: typeof PaginationQuickJumper;
+  Provider: typeof TableProvider;
+  Header: typeof TableHeaderWrapper;
+  HeaderContent: typeof TableHeaderContent;
+  Footer: typeof TableFooter;
+  FooterContent: typeof TableFooterContent;
+}
+```
+
+## Data Flow
+
+```mermaid
+flowchart TD
+    subgraph Props [Table Props]
+        dataSource["dataSource"]
+        schema["schema"]
+        loading["loading"]
+        emptyMessage["emptyMessage"]
+        customCells["customCells"]
+    end
+    
+    subgraph Context [TableContext]
+        contextValue["TableContextValue"]
+    end
+    
+    subgraph Body [Table.Body]
+        renderLogic["Render Logic"]
+    end
+    
+    subgraph Rendering [Render Output]
+        header["TableHeader (columns)"]
+        rows["TableRow[]"]
+        cells["TableCell[]"]
+        emptyState["TableMessageState"]
+    end
+    
+    Props --> Context
+    Context --> Body
+    Body --> renderLogic
+    renderLogic -->|"dataSource.length > 0"| rows
+    renderLogic -->|"dataSource.length === 0"| emptyState
+    rows --> cells
+    Body --> header
+```
+
+## Key Interfaces
+
+### TableProps
+
+```typescript
+type TableProps = {
+  cell?: {
+    hasBorder?: boolean;
+  };
+  dataSource: Record<string, unknown>[];
+  schema: TableSchema;
+  loading?: boolean;
+  emptyMessage?: string;
+  pagination?: TablePaginationConfig;
+  sort?: TableSort;
+  customCells?: Record<string, CellRenderer>;
+};
+```
+
+### TableSchema
+
+```typescript
+type TableSchemaColumn = {
+  key: string;
+  title: string | React.ReactNode;
+  cellType: CellType; // 'number' | 'boolean' | 'checkbox' | 'link' | 'avatar' | 'label' | 'description' | 'text'
+  cellRenderer?: CellRenderer;
+  hideable?: boolean;
+  sortable?: boolean;
+  valueGetter?: (record: Record<string, unknown>) => CellValue | CellProps;
+};
+
+type TableSchema = TableSchemaColumn[];
+```
+
+### TableSort
+
+```typescript
+type SortDirection = 'asc' | 'desc' | null;
+
+type SortColumn = {
+  field: string;
+  direction: SortDirection;
+};
+
+type TableSort = {
+  sortedColumns: SortColumn[];
+  onSort: (field: string, direction: SortDirection) => void;
+};
+```
+
+### TableContextValue
+
+```typescript
+interface TableContextValue extends TableProps {
+  updateSort?: (sort: TableProps['sort']) => void;
+}
+```
+
+## Sub-Components
+
+### Table.Body (TableBody)
+Main table rendering component that:
+- Reads from TableContext
+- Renders TableHeader (column headers)
+- Maps dataSource to TableRow components
+- Shows TableMessageState for empty/error states
+- Handles loading overlay
+
+### Table.Header (TableHeaderWrapper)
+Container for header content with flex layout and styling.
+
+### Table.HeaderContent (TableHeaderContent)
+Wrapper for groups of header items (search, filters, actions).
+
+### Table.Search (TableSearch)
+Input component with magnifier icon for search functionality.
+
+### Table.Footer (TableFooter)
+Container for footer content with flex layout.
+
+### Table.FooterContent (TableFooterContent)
+Wrapper for groups of footer items.
+
+### Table.Pagination (Pagination)
+Page navigation with first/prev/next/last buttons and page numbers.
+
+### Table.PaginationInfo (PaginationInfo)
+Displays "Showing X-Y of Z" information.
+
+### Table.PaginationQuickJumper (PaginationQuickJumper)
+Input for jumping directly to a specific page.
+
+## Cell Type Renderers
+
+| Cell Type | Component | Description |
+|-----------|-----------|-------------|
+| `text` | LabelCell | Plain text display |
+| `number` | NumberCell | Formatted number display |
+| `boolean` | BooleanCell | Boolean indicator |
+| `checkbox` | BooleanCell | Checkbox-style boolean |
+| `link` | LinkCell | Clickable link |
+| `avatar` | AvatarCell | Avatar image with optional text |
+| `label` | LabelCell | Styled label text |
+| `description` | DescriptionCell | Multi-line description |
+
+## Usage Example
+
+```tsx
+<Table dataSource={data} schema={schema}>
+  <Table.Header>
+    <Table.HeaderContent>
+      <Table.Search search={{ value, onChange, placeholder: 'Search...' }} />
+    </Table.HeaderContent>
+    <Table.HeaderContent>
+      <Button>Export</Button>
+    </Table.HeaderContent>
+  </Table.Header>
+  
+  <Table.Body
+    cell={{ hasBorder: true }}
+    sort={{ sortedColumns, onSort: handleSort }}
+    stickyHeader={true}
+  />
+  
+  <Table.Footer>
+    <Table.FooterContent>
+      <Table.PaginationInfo
+        showTotal={true}
+        totalItems={100}
+        currentPage={1}
+        itemsPerPage={10}
+      />
+    </Table.FooterContent>
+    <Table.FooterContent>
+      <Table.Pagination
+        currentPage={1}
+        totalPage={10}
+        onChange={setPage}
+      />
+    </Table.FooterContent>
+  </Table.Footer>
+</Table>
+```
+
+## Dependencies
+
+- `@radix-ui/react-popover` (used by search)
+- Internal `Button`, `Input` components
+- Internal icon components