Zid MUI

https://github.com/zidsa/zidmui
Admin
Zid MUI is a React component library built on the Parcel design system, providing shared components,...
Tokens:11,108
Snippets:121
Trust Score:8.1
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://github.com/zidsa/zidmui/blob/main/CONTRIBUTING.md

Run this command to install all project dependencies using pnpm.

```bash
task install
```

--------------------------------

### Install Zid MUI Package

Source: https://github.com/zidsa/zidmui/blob/main/README.md

Use this command to add the Zid MUI package to your project. Ensure you have pnpm installed.

```sh
pnpm add @zidsa/zidmui
```

--------------------------------

### Start Storybook Dev Server

Source: https://github.com/zidsa/zidmui/blob/main/CONTRIBUTING.md

Use this command to start the Storybook development server for UI component exploration. To build Storybook for production, use 'pnpm build-storybook'.

```bash
# start storybook dev server
pnpm storybook

# build storybook
pnpm build-storybook
```

--------------------------------

### Install Zid MUI and Dependencies

Source: https://context7.com/zidsa/zidmui/llms.txt

Install the Zid MUI package along with necessary peer dependencies like React, MUI, and use-debounce.

```sh
pnpm add @zidsa/zidmui
pnpm add react react-dom use-debounce @mui/material @mui/lab @emotion/styled
```

--------------------------------

### Install Zid MUI Peer Dependencies

Source: https://github.com/zidsa/zidmui/blob/main/README.md

These are the required peer dependencies for Zid MUI. Install them using pnpm.

```sh
pnpm add @zidsa/zidmui react react-dom use-debounce @mui/material @mui/lab @emotion/styled
```

--------------------------------

### Zid MUI Input Examples (CSS)

Source: https://github.com/zidsa/zidmui/blob/main/src/stories/Configure.mdx

Examples of Zid MUI input fields using CSS classes. Shows default and error states, along with helper text.

```html
<!-- Default -->
<div class="zid-input zid-input--md">
  <input type="text" class="zid-input__field" placeholder="Enter your name" />
</div>

<!-- With error state -->
<div class="zid-input zid-input--md zid-input--error">
  <input type="text" class="zid-input__field" placeholder="Email" />
</div>

<span class="zid-input-helper zid-input-helper--error">Invalid email</span>
```

--------------------------------

### Zid MUI Button Examples (CSS)

Source: https://github.com/zidsa/zidmui/blob/main/src/stories/Configure.mdx

Examples of Zid MUI buttons using CSS classes. Demonstrates primary, secondary, and disabled states with different sizes.

```html
<!-- Primary contained button -->
<button class="zid-button zid-button--contained zid-button--primary zid-button--md">
  Submit
</button>

<!-- Secondary outlined button -->
<button class="zid-button zid-button--outlined zid-button--secondary zid-button--sm">
  Cancel
</button>

<!-- Disabled button -->
<button class="zid-button zid-button--contained zid-button--primary zid-button--md" disabled>
  Disabled
</button>
```

--------------------------------

### AppIconBox: Colored Icon Container with Size Options

Source: https://context7.com/zidsa/zidmui/llms.txt

Provides examples of AppIconBox with different background colors (semantic and named) and sizes.

```tsx
import { AppIconBox } from '@zidsa/zidmui/components/app-icon-box';
import { IconMoneyDollarCircleLine } from '@zidsa/zidmui/icons/finance/money-dollar-circle-line';

<AppIconBox background="green" size="large">
  <IconMoneyDollarCircleLine />
</AppIconBox>

<AppIconBox background="red" size="medium">
  <IconAlertLine />
</AppIconBox>

<AppIconBox background="primary" size="small">
  <IconStoreLine />
</AppIconBox>
```

--------------------------------

### Setup Zid MUI Theme in React

Source: https://github.com/zidsa/zidmui/blob/main/src/stories/Configure.mdx

Configure the Zid MUI theme provider in your React application. This sets up the global theme and resets CSS baseline for consistent styling.

```jsx
import { ThemeProvider, CssBaseline } from '@mui/material';
import { themeParcel } from '@zidsa/zidmui/theme/theme';

const App = ({ children }) => {
  return (
    <ThemeProvider theme={themeParcel}>
      <CssBaseline />
      {children}
    </ThemeProvider>
  );
}
```

--------------------------------

### Zid MUI Alert Example (CSS)

Source: https://github.com/zidsa/zidmui/blob/main/src/stories/Configure.mdx

Example of a Zid MUI success alert using CSS classes. Includes placeholders for icon, title, and message content.

```html
<!-- Success Alert -->
<div class="zid-alert zid-alert--success">
  <div class="zid-alert__icon"><!-- icon svg --></div>
  <div class="zid-alert__content">
    <div class="zid-alert__title">Success</div>
    <div class="zid-alert__message">Your changes have been saved.</div>
  </div>
</div>
```

--------------------------------

### Zid MUI AppButton Examples

Source: https://context7.com/zidsa/zidmui/llms.txt

AppButton enforces valid color/variant combinations and supports tooltips via the 'tooltip' prop. It wraps MUI's Button component.

```tsx
import { AppButton } from '@zidsa/zidmui/components/app-button';

// Primary contained (default)
<AppButton color="primary" variant="contained" onClick={() => console.log('saved')}>Save</AppButton>

// Secondary outlined with tooltip
<AppButton
  color="secondary"
  variant="outlined"
  tooltip="Permanently removes the record"
  onClick={() => handleDelete()}
>
  Delete
</AppButton>

// Error contained, disabled
<AppButton color="error" variant="contained" disabled>Remove</AppButton>

// primaryDark text
<AppButton color="primaryDark" variant="text" startIcon={<EditIcon />}>Edit</AppButton>
```

--------------------------------

### Zid MUI AppAlert Examples

Source: https://context7.com/zidsa/zidmui/llms.txt

AppAlert extends MUI Alert with title, content, link, and actions slots, and supports an isLoading state. AppAlertButton is a pre-sized action button for alerts.

```tsx
import { AppAlert, AppAlertButton } from '@zidsa/zidmui/components/app-alert';

// Standard info alert with title, body, and two actions
<AppAlert
  severity="info"
  title="Subscription expiring"
  content="Your plan expires in 3 days. Renew now to avoid service interruption."
  actions={
    <>
      <AppAlertButton color="primary" variant="contained" onClick={handleRenew}>
        Renew
      </AppAlertButton>
      <AppAlertButton onClick={handleDismiss}>Dismiss</AppAlertButton>
    </>
  }
  onClose={() => setOpen(false)}
/>

// Loading state while fetching alert data
<AppAlert severity="warning" isLoading={isFetching} />

// Filled variant
<AppAlert severity="error" variant="filled" title="Payment failed" content="Check your card details." />
```

--------------------------------

### Setup IBM Plex Sans Arabic Font

Source: https://github.com/zidsa/zidmui/blob/main/src/stories/Configure.mdx

Include the IBM Plex Sans Arabic font in your HTML to ensure proper rendering of text elements using Zid MUI's typography.

```html
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Sans+Arabic:wght@400;500;600;700&display=swap" rel="stylesheet">
```

--------------------------------

### Build Project

Source: https://github.com/zidsa/zidmui/blob/main/CONTRIBUTING.md

Execute this command to build the project. For a full list of available tasks, simply run 'task'.

```bash
# run build
task build

# list all available tasks
task
```

--------------------------------

### Run Unit Tests

Source: https://github.com/zidsa/zidmui/blob/main/CONTRIBUTING.md

Execute this command to run the project's unit tests.

```bash
# unit tests
task test
```

--------------------------------

### AppTooltip: Rich Tooltip with Headline, Description, and Content

Source: https://context7.com/zidsa/zidmui/llms.txt

Shows how to create a rich tooltip using AppTooltip, splitting content into headline, description, and content slots.

```tsx
import { AppTooltip } from '@zidsa/zidmui/components/app-tooltip';
import { AppIconButton } from '@zidsa/zidmui/components/app-icon-button';
import { IconInfoLine } from '@zidsa/zidmui/icons/system/information-line';

<AppTooltip
  headline="Commission rate"
  description="Percentage deducted from each sale on this channel."
  content="Updated monthly based on your plan tier."
>
  <AppIconButton>
    <IconInfoLine />
  </AppIconButton>
</AppTooltip>
```

--------------------------------

### AppTooltip

Source: https://context7.com/zidsa/zidmui/llms.txt

A rich tooltip component that wraps MUI `Tooltip` and allows for structured content with `headline`, `description`, and `content` slots.

```APIDOC
## AppTooltip

### Description
Rich tooltip with headline and description. `AppTooltip` wraps MUI `Tooltip` and splits the tooltip content into `headline`, `description`, and `content` slots. It is arrow-topped, interactive-disabled, and delayed by 500 ms by default.

### Usage
```tsx
import { AppTooltip } from '@zidsa/zidmui/components/app-tooltip';
import { AppIconButton } from '@zidsa/zidmui/components/app-icon-button';
import { IconInfoLine } from '@zidsa/zidmui/icons/system/information-line';

<AppTooltip
  headline="Commission rate"
  description="Percentage deducted from each sale on this channel."
  content="Updated monthly based on your plan tier."
>
  <AppIconButton>
    <IconInfoLine />
  </AppIconButton>
</AppTooltip>
```
```

--------------------------------

### AppStatus: Semantic Color and Tooltip Usage

Source: https://context7.com/zidsa/zidmui/llms.txt

Illustrates using AppStatus with various semantic colors (success, warning, error, neutral) and an optional tooltip.

```tsx
import { AppStatus } from '@zidsa/zidmui/components/app-status';

<AppStatus label="Active"   color="success" size="small" />
<AppStatus label="Pending"  color="warning" size="small" />
<AppStatus label="Rejected" color="error"   size="medium" tooltip="Rejected by the review team" />
<AppStatus label="Draft"    color="neutral" />
```

--------------------------------

### AppTabs: Declarative and Prop-based Tab Configuration

Source: https://context7.com/zidsa/zidmui/llms.txt

Shows how to use AppTabs with AppTab components directly and via the 'tabs' prop for declarative configuration.

```tsx
import { AppTabs, AppTab } from '@zidsa/zidmui/components/app-tabs';
import { IconGridLine } from '@zidsa/zidmui/icons/system/grid-line';

const [tab, setTab] = useState(0);

<AppTabs value={tab} onChange={(_, v) => setTab(v)}>
  <AppTab label="All orders" value={0} chip={{ label: '24', color: 'error' }} />
  <AppTab label="Pending" value={1} icon={<IconGridLine />} chip={{ label: '5' }} />
  <AppTab label="Shipped" value={2} />
  <AppTab label="Delivered" value={3} />
</AppTabs>

// Declarative via tabs prop
<AppTabs
  value={tab}
  onChange={(_, v) => setTab(v)}
  tabs={[
    { key: 'all',       label: 'All',       value: 0 },
    { key: 'active',    label: 'Active',    value: 1, chip: { label: '12', color: 'primary' } },
    { key: 'archived',  label: 'Archived',  value: 2 },
  ]}
/>
```

--------------------------------

### Import Zid MUI Stylesheets

Source: https://github.com/zidsa/zidmui/blob/main/src/stories/Configure.mdx

Import Zid MUI styles into your project. You can import all styles at once or individual component styles for a smaller footprint.

```css
/* Import all styles */
@import '@zidsa/zidmui/styles/index.css';

/* Or import individual components */
@import '@zidsa/zidmui/styles/colors.css';
@import '@zidsa/zidmui/styles/typography.css';
@import '@zidsa/zidmui/styles/components/button.css';
@import '@zidsa/zidmui/styles/components/input.css';
```

--------------------------------

### AppIconButton: With Tooltip and Styling Options

Source: https://context7.com/zidsa/zidmui/llms.txt

Demonstrates AppIconButton with integrated tooltips, error color, and an option to hide the border.

```tsx
import { AppIconButton } from '@zidsa/zidmui/components/app-icon-button';
import { IconDeleteBinLine } from '@zidsa/zidmui/icons/system/delete-bin-line';
import { IconEditLine } from '@zidsa/zidmui/icons/system/edit-line';

<AppIconButton tooltip="Edit product" onClick={handleEdit}>
  <IconEditLine />
</AppIconButton>

<AppIconButton tooltip="Delete" color="error" onClick={handleDelete}>
  <IconDeleteBinLine />
</AppIconButton>

// No border
<AppIconButton hideBorder>
  <IconEditLine />
</AppIconButton>
```

--------------------------------

### AppTypography: Typography with Tooltip

Source: https://context7.com/zidsa/zidmui/llms.txt

Wraps MUI Typography to enforce design tokens and supports an optional tooltip.

```tsx
import { AppTypography } from '@zidsa/zidmui/components/app-typography';

<AppTypography variant="h4">Dashboard</AppTypography>
<AppTypography variant="body2" color="text.tertiary">Last updated 5 minutes ago</AppTypography>
<AppTypography variant="subtitle1" tooltip="Unique visitors in the selected period">
  Sessions: 12,430
</AppTypography>
```

--------------------------------

### AppAccordion: Controlled and Uncontrolled Modes

Source: https://context7.com/zidsa/zidmui/llms.txt

Demonstrates controlled mode with loading states and uncontrolled mode with error color and grouped rounded corners.

```tsx
import { AppAccordion } from '@zidsa/zidmui/components/app-accordion';

const [expanded, setExpanded] = useState(false);

<AppAccordion
  isOpen={expanded}
  onToggle={(_, isOpen) => setExpanded(isOpen)}
  title="Shipping settings"
  description="Configure default carriers and handling times"
  color="primary"
  isSummaryLoading={isLoadingSummary}
  isDetailsLoading={isLoadingDetails}
>
  <p>Carrier: Aramex, DHL</p>
  <p>Handling time: 1–2 business days</p>
</AppAccordion>

// Uncontrolled, error color
<AppAccordion title="Failed orders" color="error" roundedCorners="grouped">
  <p>3 orders require attention</p>
</AppAccordion>
```

--------------------------------

### Lint and Format Code

Source: https://github.com/zidsa/zidmui/blob/main/CONTRIBUTING.md

Run 'task lint' to lint and fix issues, or 'task lint-check' to only report them. Use 'pnpm format' to format the code.

```bash
# lint and fix any issues
task lint

# lint and report any issues without fixing them
task lint-check
```

```bash
pnpm format
```

--------------------------------

### Flex Layout Primitives with StackRow and StackColumn

Source: https://context7.com/zidsa/zidmui/llms.txt

StackRow and StackColumn are shorthand components for MUI Stack, providing pre-configured flex layouts. Use the 'gap' sx prop for spacing instead of the 'spacing' prop.

```tsx
import { StackRow } from '@zidsa/zidmui/components/stack-row';
import { StackColumn } from '@zidsa/zidmui/components/stack-column';

<StackRow gap={2} justifyContent="space-between">
  <AppTypography variant="subtitle1">Order total</AppTypography>
  <AppTypography variant="h6">SAR 320.00</AppTypography>
</StackRow>

<StackColumn gap={1.5} sx={{ p: 2 }}>
  <AppInputBase label="First name" name="firstName" />
  <AppInputBase label="Last name"  name="lastName" />
  <AppInputBase label="Email"      name="email" type="email" />
</StackColumn>
```

--------------------------------

### AppStatus

Source: https://context7.com/zidsa/zidmui/llms.txt

A chip-based status badge component that wraps MUI `Chip` and supports an optional `tooltip` and semantic colors.

```APIDOC
## AppStatus

### Description
Chip-based status badge. `AppStatus` is a thin wrapper around MUI `Chip` that supports an optional `tooltip` and all semantic colors defined in the Parcel palette (`primary`, `success`, `error`, `warning`, `info`, `neutral`).

### Usage
```tsx
import { AppStatus } from '@zidsa/zidmui/components/app-status';

<AppStatus label="Active"   color="success" size="small" />
<AppStatus label="Pending"  color="warning" size="small" />
<AppStatus label="Rejected" color="error"   size="medium" tooltip="Rejected by the review team" />
<AppStatus label="Draft"    color="neutral" />
```
```

--------------------------------

### AppEmptyState: Empty/Error State Illustration

Source: https://context7.com/zidsa/zidmui/llms.txt

A full-width centered component for empty or error states, supporting icons, images, text, and actions.

```tsx
import { AppEmptyState } from '@zidsa/zidmui/components/app-empty-state';
import { AppButton } from '@zidsa/zidmui/components/app-button';
import { IconShoppingBagLine } from '@zidsa/zidmui/icons/business/shopping-bag-line';

<AppEmptyState
  variant="default"
  size="standard"
  icon={<IconShoppingBagLine />}
  title="No orders yet"
  description="Once customers place orders, they will appear here."
  subDescription="Need help? Check out our getting started guide."
>
  <AppButton color="primary" variant="contained">
    Share store link
  </AppButton>
</AppEmptyState>

// Error variant with image
<AppEmptyState
  variant="error"
  imageUrl="/illustrations/error-state.svg"
  title="Failed to load products"
  description="An unexpected error occurred. Please try again."
>
  <AppButton color="secondary" variant="outlined" onClick={refetch}>
    Retry
  </AppButton>
</AppEmptyState>
```

--------------------------------

### Update Alert Theme Structure (TypeScript)

Source: https://github.com/zidsa/zidmui/blob/main/CHANGELOG.md

This code demonstrates the new alert theme structure supporting multiple variants. Access colors via standard or filled keys.

```typescript
theme.palette._components.alert.standard.error.background;
```

```typescript
theme.palette._components.alert.filled.error.background;
```

--------------------------------

### Apply Parcel Design-System Theme with ThemeProvider

Source: https://context7.com/zidsa/zidmui/llms.txt

Wrap your application with MUI's ThemeProvider using either the light or dark Parcel theme. This configures the unified palette, typography, shadows, and component overrides.

```tsx
import { ThemeProvider, CssBaseline } from '@mui/material';
import { themeParcel } from '@zidsa/zidmui/theme/theme';
import { themeParcelDark } from '@zidsa/zidmui/theme/theme.dark';

function App({ prefersDark }: { prefersDark: boolean }) {
  const theme = prefersDark ? themeParcelDark : themeParcel;

  return (
    <ThemeProvider theme={theme}>
      <CssBaseline />
      {/* All Zid MUI components respect the active theme */}
      <MyApp />
    </ThemeProvider>
  );
}
```

--------------------------------

### AppDialogWithFeatures: Dialog with Search, List, and Pagination

Source: https://context7.com/zidsa/zidmui/llms.txt

AppDialogWithFeatures extends AppDialog to include integrated search, a scrollable content area, and pagination. It's ideal for dialogs that display and manage lists of items.

```tsx
import { AppDialogWithFeatures } from '@zidsa/zidmui/components/app-dialog-with-features';
import { AppListItem } from '@zidsa/zidmui/components/app-list-item';

const [open, setOpen] = useState(false);
const [search, setSearch] = useState('');
const [page, setPage] = useState(1);

const filteredItems = allItems.filter(item =>
  item.name.toLowerCase().includes(search.toLowerCase()),
);

<AppDialogWithFeatures
  open={open}
  onClose={() => setOpen(false)}
  title="Select a product"
  search={search}
  onSearchChange={setSearch}
  pagination={{ count: Math.ceil(filteredItems.length / 10), page, onChange: (_, p) => setPage(p) }}
  isLoading={isLoading}
>
  {filteredItems.slice((page - 1) * 10, page * 10).map(item => (
    <AppListItem
      key={item.id}
      textLabel={item.name}
      textDescription={item.sku}
      onClick={() => handleSelect(item)}
    />
  ))}
</AppDialogWithFeatures>
```

--------------------------------

### Import Zid MUI Components and Hooks in React

Source: https://github.com/zidsa/zidmui/blob/main/src/stories/Configure.mdx

Import specific components, icons, and hooks from Zid MUI into your React components. Ensure the paths are correct for the desired functionality.

```jsx
import { AppButton } from '@zidsa/zidmui/components/app-button';
import { AppInputBase } from '@zidsa/zidmui/components/app-input-base';
import { IconSearchLine } from '@zidsa/zidmui/icons/system/search-line';
import { useToggle } from '@zidsa/zidmui/hooks/use-toggle';
```

--------------------------------

### Migrate Alert Theme Access (TypeScript)

Source: https://github.com/zidsa/zidmui/blob/main/CHANGELOG.md

This diff shows how to update paths when accessing alert colors from the theme due to a structure change.

```typescript
- theme.palette._components.alert.error.background
+ theme.palette._components.alert.standard.error.background
```

--------------------------------

### AppOverflownTextWithTooltip: Truncated Text with Tooltip

Source: https://context7.com/zidsa/zidmui/llms.txt

Renders single-line (ellipsis) or two-line clamped text that shows a tooltip only when text overflows.

```tsx
import { AppOverflownTextWithTooltip } from '@zidsa/zidmui/components/app-overflown-text-with-tooltip';

// Single-line truncation
<AppOverflownTextWithTooltip
  title="Blue Ceramic Coffee Mug — Extra Large (500 ml)"
  typographyProps={{ variant: 'body2', color: 'text.secondary' }}
/>

// Two-line clamp
<AppOverflownTextWithTooltip
  title="This product description is very long and will be clamped after two lines of text when it exceeds the container width."
  twoLines
  typographyProps={{ variant: 'body2' }}
/>
```

--------------------------------

### Structured List Item with AppListItem and AppListItemContent

Source: https://context7.com/zidsa/zidmui/llms.txt

AppListItem and AppListItemContent create a structured list row with typed slots for icon, text, and other elements. Long strings are automatically handled by AppOverflownTextWithTooltip.

```tsx
import { AppListItem, AppListItemContent } from '@zidsa/zidmui/components/app-list-item';
import { AppStatus } from '@zidsa/zidmui/components/app-status';
import { IconStoreLine } from '@zidsa/zidmui/icons/business/store-line';

<AppListItem
  icon={<IconStoreLine />}
  textLabel="Riyadh Flagship Store"
  textDescription="Riyadh, Al Olaya district"
  textContent="SKU-7890"
  labelSuffix={<AppStatus label="Active" color="success" size="small" />}
  tooltip="Store identifier used in API calls"
/>
```

--------------------------------

### AppAccordion

Source: https://context7.com/zidsa/zidmui/llms.txt

An expandable accordion component that supports controlled and uncontrolled modes, semantic color variants, and independent loading states for its summary and details.

```APIDOC
## AppAccordion

### Description
Expandable accordion with loading states. Supports controlled (`isOpen` / `onToggle`) and uncontrolled modes, semantic color variants, and independent loading states for the summary header and the details body.

### Usage
```tsx
import { AppAccordion } from '@zidsa/zidmui/components/app-accordion';

const [expanded, setExpanded] = useState(false);

<AppAccordion
  isOpen={expanded}
  onToggle={(_, isOpen) => setExpanded(isOpen)}
  title="Shipping settings"
  description="Configure default carriers and handling times"
  color="primary"
  isSummaryLoading={isLoadingSummary}
  isDetailsLoading={isLoadingDetails}
>
  <p>Carrier: Aramex, DHL</p>
  <p>Handling time: 1–2 business days</p>
</AppAccordion>

// Uncontrolled, error color
<AppAccordion title="Failed orders" color="error" roundedCorners="grouped">
  <p>3 orders require attention</p>
</AppAccordion>
```
```

--------------------------------

### AppIconButton

Source: https://context7.com/zidsa/zidmui/llms.txt

An icon button component that wraps MUI `IconButton` and automatically includes an `AppTooltip` if a `tooltip` prop is provided.

```APIDOC
## AppIconButton

### Description
Icon button with optional tooltip. `AppIconButton` wraps MUI `IconButton` and auto-wraps the button in an `AppTooltip` when a `tooltip` string is provided.

### Usage
```tsx
import { AppIconButton } from '@zidsa/zidmui/components/app-icon-button';
import { IconDeleteBinLine } from '@zidsa/zidmui/icons/system/delete-bin-line';
import { IconEditLine } from '@zidsa/zidmui/icons/system/edit-line';

<AppIconButton tooltip="Edit product" onClick={handleEdit}>
  <IconEditLine />
</AppIconButton>

<AppIconButton tooltip="Delete" color="error" onClick={handleDelete}>
  <IconDeleteBinLine />
</AppIconButton>

// No border
<AppIconButton hideBorder>
  <IconEditLine />
</AppIconButton>
```
```

--------------------------------

### AppSwitch / AppSwitchGroup: Toggle Switch

Source: https://context7.com/zidsa/zidmui/llms.txt

AppSwitch renders a labeled or standalone MUI Switch. AppSwitchGroup renders a group of switches with optional labels and helper text.

```tsx
import { AppSwitch, AppSwitchGroup } from '@zidsa/zidmui/components/app-switch';
// AppSwitchGroup is imported from app-switch-group
import { AppSwitchGroup } from '@zidsa/zidmui/components/app-switch-group';

// Single switch with label
<AppSwitch
  name="notifications"
  label="Email notifications"
  switchProps={{ checked: enabled, onChange: (e) => setEnabled(e.target.checked) }}
/>

// Group of switches
<AppSwitchGroup
  label="Notification channels"
  helperText="Choose how you want to receive updates"
  options={[
    { name: 'email',  label: 'Email',  switchProps: { checked: prefs.email,  onChange: (e) => update('email', e.target.checked) } },
    { name: 'sms',    label: 'SMS',    switchProps: { checked: prefs.sms,    onChange: (e) => update('sms', e.target.checked) } },
    { name: 'push',   label: 'Push',   switchProps: { checked: prefs.push,   onChange: (e) => update('push', e.target.checked) } },
  ]}
/>
```

--------------------------------

### AppIconBox

Source: https://context7.com/zidsa/zidmui/llms.txt

A component that renders a colored icon container, providing a rounded-square box with a semantic background color to visually group icons.

```APIDOC
## AppIconBox

### Description
Colored icon container. Renders a rounded-square box with a semantic background color to visually group an icon with a meaning (e.g., a green box for a success icon).

### Usage
```tsx
import { AppIconBox } from '@zidsa/zidmui/components/app-icon-box';
import { IconMoneyDollarCircleLine } from '@zidsa/zidmui/icons/finance/money-dollar-circle-line';

<AppIconBox background="green" size="large">
  <IconMoneyDollarCircleLine />
</AppIconBox>

<AppIconBox background="red" size="medium">
  <IconAlertLine />
</AppIconBox>

<AppIconBox background="primary" size="small">
  <IconStoreLine />
</AppIconBox>
```
```

--------------------------------

### Boolean State Management with useToggle Hook

Source: https://context7.com/zidsa/zidmui/llms.txt

The useToggle hook manages boolean state and provides named helper functions (on, off, toggle, setValue) for easier state manipulation. It also includes a preventEvent.Default helper.

```tsx
import { useToggle } from '@zidsa/zidmui/hooks/use-toggle';

function DeleteConfirmation() {
  const dialog = useToggle(false);

  return (
    <>
      <AppButton color="error" variant="outlined" onClick={dialog.on}>
        Delete product
      </AppButton>

      <AppDialog
        open={dialog.value}
        onClose={dialog.off}
        title="Confirm deletion"
        actions={
          <>
            <AppButton color="secondary" variant="outlined" onClick={dialog.off}>Cancel</AppButton>
            <AppButton color="error" variant="contained" onClick={handleDelete}>Delete</AppButton>
          </>
        }
      />
    </>
  );
}
```

--------------------------------

### AppDialog: Structured Modal Dialog

Source: https://context7.com/zidsa/zidmui/llms.txt

Use AppDialog for structured modal dialogs with predefined slots for title, description, and actions. It composes MUI Dialog with sensible defaults like fullWidth and maxWidth.

```tsx
import { AppDialog } from '@zidsa/zidmui/components/app-dialog';
import { AppButton } from '@zidsa/zidmui/components/app-button';

const [open, setOpen] = useState(false);

<AppButton onClick={() => setOpen(true)}>Open dialog</AppButton>

<AppDialog
  open={open}
  onClose={() => setOpen(false)}
  title="Confirm deletion"
  description="This action cannot be undone. All associated data will be permanently removed."
  darkerBackdrop
  actions={
    <>
      <AppButton color="secondary" variant="outlined" onClick={() => setOpen(false)}>
        Cancel
      </AppButton>
      <AppButton color="error" variant="contained" onClick={handleConfirm}>
        Delete
      </AppButton>
    </>
  }
>
  {/* Optional extra body content */}
  <p>Product: <strong>Blue Widget (SKU-1234)</strong></p>
</AppDialog>
```

--------------------------------

### AppCheckbox: Labeled Checkbox

Source: https://context7.com/zidsa/zidmui/llms.txt

Combines MUI Checkbox with FormControlLabel for standardized icon sizing and labeling.

```tsx
import { AppCheckbox } from '@zidsa/zidmui/components/app-checkbox';

const [agreed, setAgreed] = useState(false);

<AppCheckbox
  name="terms"
  label="I agree to the terms and conditions"
  checked={agreed}
  onChange={(e) => setAgreed(e.target.checked)}
/>

// Indeterminate via checkboxProps passthrough
<AppCheckbox
  name="select-all"
  label="Select all"
  checked={allSelected}
  checkboxProps={{ indeterminate: someSelected && !allSelected }}
  onChange={handleSelectAll}
/>
```

--------------------------------

### Using Zid MUI Icons

Source: https://context7.com/zidsa/zidmui/llms.txt

Import and use Zid MUI icons as React SVG components. They support standard MUI props like `fontSize`, `color`, and `sx`. Icons can also be used within `AppIconBox` or as `startIcon`/`endIcon` in `AppButton`.

```tsx
import { IconArrowDownLine }        from '@zidsa/zidmui/icons/arrows/arrow-down-line';
import { IconStoreLine }            from '@zidsa/zidmui/icons/business/store-line';
import { IconMoneyDollarCircleLine } from '@zidsa/zidmui/icons/finance/money-dollar-circle-line';
import { IconSearchLine }           from '@zidsa/zidmui/icons/system/search-line';

// Used directly as MUI SvgIcon — supports fontSize, color, sx props
<IconArrowDownLine fontSize="small" color="action" />
<IconStoreLine fontSize="large" sx={{ color: 'primary.main' }} />

// Used inside AppIconBox
<AppIconBox background="primary" size="medium">
  <IconMoneyDollarCircleLine />
</AppIconBox>

// Used in AppButton startIcon / endIcon
<AppButton color="primary" variant="contained" startIcon={<IconSearchLine />}>
  Search
</AppButton>
```

--------------------------------

### AppTabs and AppTab

Source: https://context7.com/zidsa/zidmui/llms.txt

A scrollable tab bar component (`AppTabs`) that renders an indicator-hidden MUI `Tabs` strip. Each `AppTab` can include an optional icon and a `chip` badge.

```APIDOC
## AppTabs / AppTab

### Description
Scrollable tab bar. `AppTabs` renders a scrollable, indicator-hidden MUI `Tabs` strip. Each `AppTab` supports an optional icon and a `chip` badge (rendered as `AppStatus`).

### Usage
```tsx
import { AppTabs, AppTab } from '@zidsa/zidmui/components/app-tabs';
import { IconGridLine } from '@zidsa/zidmui/icons/system/grid-line';

const [tab, setTab] = useState(0);

<AppTabs value={tab} onChange={(_, v) => setTab(v)}>
  <AppTab label="All orders" value={0} chip={{ label: '24', color: 'error' }} />
  <AppTab label="Pending" value={1} icon={<IconGridLine />} chip={{ label: '5' }} />
  <AppTab label="Shipped" value={2} />
  <AppTab label="Delivered" value={3} />
</AppTabs>

// Declarative via tabs prop
<AppTabs
  value={tab}
  onChange={(_, v) => setTab(v)}
  tabs={[
    { key: 'all',       label: 'All',       value: 0 },
    { key: 'active',    label: 'Active',    value: 1, chip: { label: '12', color: 'primary' } },
    { key: 'archived',  label: 'Archived',  value: 2 },
  ]}
/>
```
```

--------------------------------

### Debounced State Management with useDebounceState Hook

Source: https://context7.com/zidsa/zidmui/llms.txt

useDebounceState returns a debounced value, a setter function, and the raw value. The debounced value updates after a delay, useful for inputs where immediate state changes are not desired, like search queries.

```tsx
import { useDebounceState } from '@zidsa/zidmui/hooks/use-debounce-state';

function ProductSearch() {
  const [debouncedQuery, setQuery, rawQuery] = useDebounceState<string>('', 300);

  // Fires API only after user stops typing for 300 ms
  useEffect(() => {
    if (debouncedQuery) fetchProducts(debouncedQuery);
  }, [debouncedQuery]);

  return (
    <AppInputBaseSearch
      name="search"
      value={rawQuery}
      onChange={(e) => setQuery(e.target.value)}
      placeholder="Search products..."
    />
  );
}
```

--------------------------------

### AppInputBase: Extended MUI TextField

Source: https://context7.com/zidsa/zidmui/llms.txt

Use AppInputBase for enhanced text fields with adornments, text transformation, and label suffixes. It wraps MUI TextField and provides slots for start/end adornments and text processing.

```tsx
import { AppInputBase } from '@zidsa/zidmui/components/app-input-base';
import { IconSearchLine } from '@zidsa/zidmui/icons/system/search-line';

// Price input with currency adornment and numeric transform
<AppInputBase
  label="Price"
  labelSuffix={<span style={{ color: 'gray' }}>(required)</span>}
  startAdornmentText="SAR"
  endAdornmentText="per unit"
  transformText={(text) => text.replace(/[^0-9.]/g, '')}
  value={price}
  onChange={(e) => setPrice(e.target.value)}
  helperText="Enter the selling price"
/>

// Search field with icon adornment
<AppInputBase
  label="Search products"
  startAdornment={<IconSearchLine fontSize="small" />}
  size="small"
  fullWidth
  value={query}
  onChange={(e) => setQuery(e.target.value)}
/>
```

--------------------------------

### Update Alert Dark Theme Colors (TypeScript)

Source: https://github.com/zidsa/zidmui/blob/main/CHANGELOG.md

This commit updates the dark theme colors for the alert component.

```typescript
theme.palette._components.alert.error.background;
```

```typescript
theme.palette._components.alert.error.color;
```

--------------------------------

### Outlined Rounded Pagination with AppPagination

Source: https://context7.com/zidsa/zidmui/llms.txt

AppPagination is a pre-configured MUI Pagination component with specific styling and first/last page buttons enabled. Use it for navigating through paginated content.

```tsx
import { AppPagination } from '@zidsa/zidmui/components/app-pagination';

const [page, setPage] = useState(1);

<AppPagination
  count={totalPages}
  page={page}
  onChange={(_, newPage) => setPage(newPage)}
  size="medium"
/>
```

--------------------------------

### AppCard: Sectioned Content Card

Source: https://context7.com/zidsa/zidmui/llms.txt

AppCard provides a structured card component for displaying sections of content. It enhances MUI Card with props for titles, descriptions, actions, and loading states.

```tsx
import { AppCard } from '@zidsa/zidmui/components/app-card';
import { AppButton } from '@zidsa/zidmui/components/app-button';
import { AppStatus } from '@zidsa/zidmui/components/app-status';

<AppCard
  color="primary"
  title="Monthly revenue"
  titleSuffix={<AppStatus label="Live" color="success" />}
  titleAction={<AppButton color="secondary" variant="text" size="small">View report</AppButton>}
  description="Aggregated from all active stores"
  titleDivider
  actions={<AppButton color="primary" variant="contained">Export CSV</AppButton>}
>
  <p style={{ fontSize: 32, fontWeight: 700 }}>SAR 142,500</p>
</AppCard>
```

--------------------------------

### Client-side Pagination with usePaginatedData Hook

Source: https://context7.com/zidsa/zidmui/llms.txt

Use this hook to manage client-side pagination for large datasets. It returns the current page slice, page number, limit, and functions to change the page and limit.

```tsx
import { usePaginatedData } from '@zidsa/zidmui/hooks/use-paginated-data';
import { AppPagination } from '@zidsa/zidmui/components/app-pagination';

function OrderTable({ orders }: { orders: Order[] }) {
  const { data, page, pagesCount, onPageChange } = usePaginatedData({
    data: orders,
    perPage: 15,
  });

  return (
    <>
      <table>
        {data.map(order => (
          <tr key={order.id}>
            <td>{order.id}</td>
            <td>{order.total}</td>
          </tr>
        ))}
      </table>
      <AppPagination count={pagesCount} page={page} onChange={(_, p) => onPageChange(p)} />
    </>
  );
}
```

--------------------------------

### DOM Custom Events with useCustomEventListener and triggerCustomEvent

Source: https://context7.com/zidsa/zidmui/llms.txt

Use `useCustomEventListener` to listen for custom DOM events within React components and `triggerCustomEvent` to dispatch them with an optional payload. The hook cleans up the listener on unmount.

```tsx
import {
  useCustomEventListener,
  triggerCustomEvent,
} from '@zidsa/zidmui/hooks/use-custom-event-listener';

// In any component — listen for a cart update event
function CartBadge() {
  const [count, setCount] = useState(0);

  useCustomEventListener('cart:updated', (event) => {
    setCount(event?.detail?.itemCount ?? 0);
  });

  return <AppStatus label={String(count)} color="error" />;
}

// Trigger the event from anywhere in the app
function AddToCartButton({ productId }: { productId: string }) {
  const handleAdd = async () => {
    await addToCart(productId);
    triggerCustomEvent('cart:updated', { itemCount: getCartCount() });
  };

  return (
    <AppButton color="primary" variant="contained" onClick={handleAdd}>
      Add to cart
    </AppButton>
  );
}
```

--------------------------------

### Controlled Radio Group with AppRadioGroup

Source: https://context7.com/zidsa/zidmui/llms.txt

Use AppRadioGroup to render a labeled radio group from an options array. It enforces uniform Radio controls within the group.

```tsx
import { AppRadioGroup } from '@zidsa/zidmui/components/app-radio-group';

const [fulfillment, setFulfillment] = useState('zid');

<AppRadioGroup
  name="fulfillment"
  label="Fulfillment method"
  value={fulfillment}
  onChange={(e) => setFulfillment(e.target.value)}
  row={false}
  options={[
    { value: 'zid',    label: 'Fulfilled by Zid' },
    { value: 'seller', label: 'Fulfilled by seller' },
    { value: 'pickup', label: 'In-store pickup' },
  ]}
/>
```

--------------------------------

### AppInputBaseSearch: Search Input Component

Source: https://context7.com/zidsa/zidmui/llms.txt

AppInputBaseSearch is a specialized search input that pre-attaches a search icon. It simplifies creating search fields by extending AppInputBase.

```tsx
import { AppInputBaseSearch } from '@zidsa/zidmui/components/app-input-base-search';

<AppInputBaseSearch
  name="product-search"
  label="Search"
  size="small"
  fullWidth
  value={searchTerm}
  onChange={(e) => setSearchTerm(e.target.value)}
  transformText={(text) => text.toLowerCase()}
/>
```
Tokens:
Raw