# Customize Fields Panel (`customize-fields-panel`) - SignalOS widget

> Generic filter/option panel composing segmented groups, dropdown selects, switches, and text inputs under Filters/Options sections - used to build any 'customize this action' surface.

- **Version:** 0.1.0
- **Kind:** widget · **Category:** inputs
- **Install:** `npx shadcn@4.1.2 add @signalos/customize-fields-panel`
- **Registry dependencies (pulled automatically):** @signalos/tokens, @signalos/utils, @signalos/input, @signalos/label, @signalos/select, @signalos/switch, @signalos/tooltip, @signalos/filter-toolbar
- **npm dependencies:** none
- **Files installed:** `src/components/widgets/customize-fields-panel/CustomizeFieldsPanel.tsx`, `src/components/widgets/customize-fields-panel/CustomizeFieldsPanel.types.ts`, `src/components/widgets/customize-fields-panel/CustomizeFieldsPanel.constants.ts`, `src/components/widgets/customize-fields-panel/CustomizeFieldsPanel.utils.ts`

## Access

This is a private registry: pulling source requires a `SIGNALOS_REGISTRY_TOKEN`
(GitHub fine-grained PAT with read access to the signal-widgets repo) and an
`@signalos` entry in components.json `"registries"`. Previews and this document are public.

## Usage

```tsx
import { CustomizeFieldsPanel } from "@/components/widgets/customize-fields-panel/CustomizeFieldsPanel"
```

## Example

```tsx
// Example: the snippet shown as public example code in the catalog.
import { useState } from "react"

import { CustomizeFieldsPanel } from "@/components/widgets/customize-fields-panel/CustomizeFieldsPanel"

export default function Example() {
  const [severity, setSeverity] = useState("high")
  const [includeArchived, setIncludeArchived] = useState(false)

  return (
    <CustomizeFieldsPanel
      segments={[
        {
          key: "severity",
          value: severity,
          onChange: setSeverity,
          options: [
            { value: "high", label: "High" },
            { value: "low", label: "Low" },
          ],
        },
      ]}
      switches={[
        {
          key: "archived",
          label: "Include archived",
          checked: includeArchived,
          onChange: setIncludeArchived,
        },
      ]}
    />
  )
}
```

## Props

### `SwitchFieldGroup`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key` | `string` | yes | - |  |
| `label` | `ReactNode` | yes | - |  |
| `checked` | `boolean` | yes | - |  |
| `onChange` | `(checked: boolean) => void` | yes | - |  |

### `TextFieldGroup`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key` | `string` | yes | - |  |
| `label` | `ReactNode` | yes | - |  |
| `value` | `string` | yes | - |  |
| `onChange` | `(value: string) => void` | yes | - |  |
| `placeholder` | `string \| undefined` | no | - |  |
| `type` | `"number" \| "text" \| undefined` | no | `"text"` |  |
| `min` | `number \| undefined` | no | - | Applied when `type` is "number". |
| `max` | `number \| undefined` | no | - |  |

### `CustomizeFieldsPanelProps`

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `segments` | `readonly FilterSegmentGroup[] \| undefined` | no | - | Segmented single-select button groups (e.g. severity, deadline). |
| `selects` | `readonly FilterSelectGroup[] \| undefined` | no | - | Dropdown select groups (e.g. role, category). |
| `switches` | `readonly SwitchFieldGroup[] \| undefined` | no | - | Boolean toggle fields (e.g. "include archived"). |
| `inputs` | `readonly TextFieldGroup[] \| undefined` | no | - | Manually-entered text/number fields (e.g. a role id, a record limit). |
| `filtersLabel` | `string \| undefined` | no | `"Filters"` | Heading shown above `segments`/`selects`. |
| `optionsLabel` | `string \| undefined` | no | `"Options"` | Heading shown above `inputs`/`switches`. |
| `className` | `string \| undefined` | no | - |  |
| `data-testid` | `string \| undefined` | no | - | Test identifier rendered as `data-testid` on the root element. |

## Changelog

# customize-fields-panel

## 0.1.0

- Initial release: a generic filter/option panel composing segmented button
  groups, dropdown selects, switches, and text/number inputs under a
  "Filters" and an "Options" section (both labels overridable via
  `filtersLabel`/`optionsLabel`). Carries no domain vocabulary of its own -
  extracted from the print-customize panel so it can back any "customize this
  action" surface, not just print.