### Run Development Setup

Source: https://github.com/bpmn-io/properties-panel/blob/main/README.md

Starts the full development environment for the project. Use this for active development and debugging.

```sh
npm run dev
```

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

### Install Dependencies

Source: https://github.com/bpmn-io/properties-panel/blob/main/README.md

Installs all project dependencies. Run this before other build or development commands.

```sh
npm install
```

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

### Header Component Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Header.md

Demonstrates how to implement and use the Header component with a custom HeaderProvider. This example shows how to provide labels, icons, and documentation references for different element types.

```javascript
import { Header } from '@bpmn-io/properties-panel';
import ServiceTaskIcon from './icons/ServiceTaskIcon';
import UserTaskIcon from './icons/UserTaskIcon';

const headerProvider = {
  getElementLabel: (element) => element.name || element.id,
  
  getTypeLabel: (element) => {
    if (element.$type === 'bpmn:ServiceTask') {
      return 'Service Task';
    }
    if (element.$type === 'bpmn:UserTask') {
      return 'User Task';
    }
    return element.$type;
  },
  
  getElementIcon: (element) => {
    if (element.$type === 'bpmn:ServiceTask') {
      return ServiceTaskIcon;
    }
    if (element.$type === 'bpmn:UserTask') {
      return UserTaskIcon;
    }
    return null;
  },
  
  getDocumentationRef: (element) => {
    return `https://docs.example.com/${element.$type}`;
  }
};

// In your panel component:
<Header 
  element={selectedElement}
  headerProvider={headerProvider}
/>
```

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

### DescriptionContext Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Use the DescriptionContext to display description text for an entry. This example retrieves the description using getDescriptionForId and conditionally renders it.

```javascript
function CustomEntry(props) {
  const { getDescriptionForId } = useContext(DescriptionContext);
  const description = getDescriptionForId(props.id, props.element);
  
  return (
    <div>
      <label>{props.label}</label>
      <input />
      {description && (
        <p className="description">{description}</p>
      )}
    </div>
  );
}
```

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

### Add a Dropdown Select Entry

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/INDEX.md

Example of how to configure a SelectEntry for a property. Use this for selecting a value from a predefined list of options.

```javascript
{
  id: 'status',
  component: SelectEntry,
  isEdited: (node) => !!node?.value
}
```

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

### TypeScript Ambient Definitions Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/types.md

Example of how to write ambient type definitions for the @bpmn-io/properties-panel package in a TypeScript project.

```typescript
declare module '@bpmn-io/properties-panel' {
  export interface GroupDefinition {
    component?: any;
    entries: EntryDefinition[];
    id: string;
    label: string | any;
    shouldOpen?: boolean;
    translate?: (key: string) => string;
    tooltip?: string | any;
  }
  // ... other types
}
```

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

### useEvent Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Provides an example of using the useEvent hook to listen for the 'propertiesPanel.showEntry' event and update a component's state with the ID of the shown entry.

```javascript
function MyComponent(props) {
  const [notifications, setNotifications] = useState([]);
  
  useEvent('propertiesPanel.showEntry', (event) => {
    setNotifications(prev => [...prev, event.id]);
  });
  
  return <div>{/* ... */}</div>;
}
```

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

### PropertiesPanel Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/PropertiesPanel.md

Demonstrates how to use the PropertiesPanel component with custom header provider and groups. Ensure you have the necessary state management and component imports.

```javascript
import { PropertiesPanel } from '@bpmn-io/properties-panel';
import { TextFieldEntry } from '@bpmn-io/properties-panel';

function MyPanel() {
  const [element, setElement] = useState(null);

  const headerProvider = {
    getElementLabel: (el) => el.name || 'Element',
    getTypeLabel: (el) => el.$type,
    getElementIcon: (el) => <IconComponent />,
    getDocumentationRef: (el) => 'https://docs.example.com'
  };

  const groups = [
    {
      id: 'general',
      label: 'General',
      entries: [
        {
          id: 'name',
          component: TextFieldEntry,
          isEdited: (node) => !!node?.value
        }
      ]
    }
  ];

  return (
    <PropertiesPanel
      element={element}
      groups={groups}
      headerProvider={headerProvider}
    />
  );
}
```

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

### Icon Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/UtilityComponents.md

Demonstrates how to use pre-built icons like CreateIcon and DeleteIcon within buttons. Icons can be imported and rendered directly, often alongside text.

```javascript
import { CreateIcon, DeleteIcon } from '@bpmn-io/properties-panel';

<button>
  <CreateIcon width="16" height="16" />
  Add Item
</button>

<button>
  <DeleteIcon width="16" height="16" />
  Delete
</button>
```

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

### Full Validation Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/errors.md

An example demonstrating how to perform multiple validations (required, length, format, range, selection) and report them using `propertiesPanel.setErrors` within a `useEffect` hook.

```javascript
import { useErrors } from '@bpmn-io/properties-panel';
import { useEffect } from 'preact/hooks';

function MyPanel(props) {
  const { element, eventBus } = props;
  
  useEffect(() => {
    const errors = {};
    
    // Validate name
    if (!element.name || element.name.trim() === '') {
      errors['name'] = 'Name is required';
    } else if (element.name.length > 100) {
      errors['name'] = 'Name must be less than 100 characters';
    }
    
    // Validate email
    if (element.email && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(element.email)) {
      errors['email'] = 'Invalid email format';
    }
    
    // Validate age
    const age = parseInt(element.age);
    if (!isNaN(age) && (age < 0 || age > 150)) {
      errors['age'] = 'Age must be between 0 and 150';
    }
    
    // Validate selection
    if (!element.type) {
      errors['type'] = 'Please select a type';
    }
    
    // Fire errors event
    eventBus.fire('propertiesPanel.setErrors', { errors });
  }, [element, eventBus]);
  
  return <PropertiesPanel {...props} />;
}
```

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

### Usage Example for Group Component

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Demonstrates how to use the LayoutContext to manage the open/closed state of a group component and persist this state.

```javascript
function Group(props) {
  const { getLayoutForKey, setLayoutForKey } = useContext(LayoutContext);
  
  const [open, setOpen] = useState(
    getLayoutForKey(['groups', props.id, 'open'], props.shouldOpen)
  );
  
  const toggleOpen = () => {
    const newValue = !open;
    setOpen(newValue);
    setLayoutForKey(['groups', props.id, 'open'], newValue);
  };
  
  return (
    <div>
      <button onClick={toggleOpen}>
        {open ? 'Collapse' : 'Expand'}
      </button>
      {open && <Content />}
    </div>
  );
}
```

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

### Placeholder Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/GroupComponents.md

Demonstrates how to configure and use the Placeholder component within the PropertiesPanel, providing custom content for empty and multiple element selection states.

```javascript
const placeholderProvider = {
  getEmpty: () => ({
    icon: EmptyIcon,
    text: 'No element selected',
    secondaryText: 'Select an element to edit properties'
  }),
  getMultiple: () => ({
    icon: MultiIcon,
    text: 'Multiple elements selected',
    secondaryText: 'Select a single element to edit'
  })
};

<PropertiesPanel
  element={element}
  placeholderProvider={placeholderProvider}
  groups={groups}
/>
```

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

### Add Tooltips to Properties

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/INDEX.md

Example configuration for adding tooltips to properties. Tooltips provide additional information when hovering over an element.

```javascript
const tooltipConfig = {
  'name': () => 'The name uniquely identifies this element',
  'email': () => 'Enter a valid email address'
};
```

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

### Group Component Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/GroupComponents.md

Demonstrates how to configure and use the Group component to structure properties within the PropertiesPanel. Ensure 'element' and 'groups' are correctly passed.

```javascript
const groups = [
  {
    id: 'general',
    label: 'General Properties',
    shouldOpen: true,
    entries: [
      {
        id: 'name',
        component: TextFieldEntry
      },
      {
        id: 'description',
        component: TextAreaEntry
      }
    ]
  }
];

<PropertiesPanel
  element={element}
  groups={groups}
/>
```

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

### useDescriptionContext Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Illustrates the usage of useDescriptionContext to display a help text below an input field if a description is available for the entry. This enhances user guidance.

```javascript
function MyEntry(props) {
  const description = useDescriptionContext(props.id, props.element);
  
  return (
    <div>
      <label>{props.label}</label>
      <input />
      {description && <p className="help-text">{description}</p>}
    </div>
  );
}
```

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

### Add a List Group Entry

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/INDEX.md

Example of how to configure a ListGroup for managing a collection of items. Supports adding and removing items.

```javascript
{
  id: 'items',
  component: ListGroup,
  add: handleAddItem,
  items: element.items.map(item => ({
    id: item.id,
    label: item.name,
    entries: [/* ... */],
    remove: handleRemoveItem(item.id)
  }))
}
```

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

### Add Descriptions to Properties

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/INDEX.md

Example configuration for adding descriptive text to properties. This is useful for providing context or help to the user.

```javascript
const descriptionConfig = {
  'name': () => 'Unique element identifier',
  'email': () => 'Valid email address required'
};
```

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

### Custom Styling

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/UtilityComponents.md

Instructions and examples for overriding the default styles of the properties panel components using CSS.

```APIDOC
## Custom Styling

Override styles with CSS:

```css
.bio-properties-panel-input {
  border: 2px solid #ccc;
  padding: 8px;
}

.bio-properties-panel-input:focus {
  border-color: #0066cc;
}

.bio-properties-panel-entry {
  margin-bottom: 12px;
}
```
```

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

### Add a Text Property Entry

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/INDEX.md

Example of how to configure a TextFieldEntry for a property. Use this when you need a simple text input field.

```javascript
{
  id: 'name',
  component: TextFieldEntry,
  isEdited: (node) => !!node?.value
}
```

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

### Add a Checkbox Entry

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/INDEX.md

Example of how to configure a CheckboxEntry for a boolean property. Use this for simple true/false toggles.

```javascript
{
  id: 'enabled',
  component: CheckboxEntry,
  isEdited: (node) => node?.checked !== false
}
```

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

### Complete Properties Panel Configuration

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/configuration.md

This snippet shows a comprehensive configuration object for the PropertiesPanel, including element selection, header and placeholder providers, group definitions, and event bus integration. Use this as a starting point for setting up the panel.

```javascript
import { PropertiesPanel } from '@bpmn-io/properties-panel';
import {
  TextFieldEntry,
  TextAreaEntry,
  SelectEntry,
  CheckboxEntry
} from '@bpmn-io/properties-panel';

const config = {
  element: selectedElement,
  
  headerProvider: {
    getElementLabel: (el) => el.name,
    getTypeLabel: (el) => el.$type,
    getElementIcon: (el) => IconComponent,
    getDocumentationRef: (el) => 'https://docs.example.com'
  },
  
  placeholderProvider: {
    getEmpty: () => ({ text: 'No element selected' }),
    getMultiple: () => ({ text: 'Multiple selected' })
  },
  
  groups: [
    {
      id: 'general',
      label: 'General',
      shouldOpen: true,
      entries: [
        {
          id: 'name',
          component: TextFieldEntry,
          isEdited: (node) => !!node?.value
        },
        {
          id: 'description',
          component: TextAreaEntry,
          isEdited: (node) => !!node?.value
        },
        {
          id: 'type',
          component: SelectEntry,
          isEdited: (node) => !!node?.value
        }
      ]
    }
  ],
  
  descriptionConfig: {
    'name': () => 'The element name',
    'description': () => 'Element description'
  },
  
  tooltipConfig: {
    'name': () => 'Enter the element name'
  },
  
  layoutConfig: {
    groups: {
      'general': { open: true }
    }
  },
  
  eventBus: eventBusInstance
};

<PropertiesPanel {...config} />
```

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

### ListGroup Component Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/GroupComponents.md

Illustrates how to implement ListGroup for managing dynamic lists of items, including add and remove functionalities. Ensure callbacks and item mapping are correctly defined.

```javascript
const handleAddItem = () => {
  // Create new item in the element
  const newItem = { id: generateId(), name: '' };
  element.items = [...(element.items || []), newItem];
  updateDiagram();
};

const handleRemoveItem = (itemId) => {
  return (event) => {
    event.preventDefault();
    element.items = element.items.filter(item => item.id !== itemId);
    updateDiagram();
  };
};

const groups = [
  {
    id: 'items',
    label: 'Items',
    component: ListGroup,
    add: handleAddItem,
    element,
    items: (element.items || []).map(item => ({
      id: item.id,
      label: item.name || 'Unnamed',
      autoFocusEntry: 'itemName',
      entries: [
        {
          id: 'itemName',
          component: TextFieldEntry
        },
        {
          id: 'itemValue',
          component: TextFieldEntry
        }
      ],
      remove: handleRemoveItem(item.id)
    }))
  }
];

<PropertiesPanel
  element={element}
  groups={groups}
/>
```

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

### useErrors Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Shows an example of using the useErrors hook to determine if any entries within a group have validation errors, indicated by checking the returned errors object.

```javascript
function Group(props) {
  const allErrors = useErrors();
  const hasErrors = props.entries.some(e => allErrors[e.id]);
  
  return (
    <div className={hasErrors ? 'error-state' : ''}>
      {/* render entries */}
    </div>
  );
}
```

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

### useLayoutState Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Demonstrates how to use the useLayoutState hook to manage the open/closed state of a group in the properties panel. It utilizes the hook to toggle the visibility of group content.

```javascript
function Group(props) {
  const [open, setOpen] = useLayoutState(['groups', props.id, 'open'], false);
  
  return (
    <div>
      <button onClick={() => setOpen(!open)}>Toggle</button>
      {open && <Content />}
    </div>
  );
}
```

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

### FeelEntry Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Features.md

Use the `useEvent` hook and `eventBus.fire` to trigger the opening of a FEEL popup from an entry component. Ensure to provide necessary details like `entryId`, `element`, and `sourceElement`.

```javascript
import { useEvent } from '@bpmn-io/properties-panel';

function FeelEntry(props) {
  const { eventBus } = useContext(EventContext);
  
  const handleOpenPopup = () => {
    eventBus.fire('propertiesPanel.openPopup', {
      entryId: props.id,
      element: props.element,
      label: 'FEEL Expression',
      value: props.value,
      sourceElement: inputRef.current,
      type: 'feel'
    });
  };
  
  return (
    <div>
      <input value={props.value} />
      <button onClick={handleOpenPopup}>Open Editor</button>
    </div>
  );
}
```

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

### PropertiesPanel.md

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/README.md

Documentation for the main PropertiesPanel component, including its signature, props, type definitions, interfaces, context providers, events, styling, and usage examples.

```APIDOC
## PropertiesPanel Component

### Description
Provides the main interface for the properties panel, allowing users to view and edit properties of BPMN elements. It integrates various input fields, grouping mechanisms, and event handling.

### Component Signature
```typescript
PropertiesPanel(props: PropertiesPanelProps)
```

### Props
- **modeler**: The BPMN modeler instance.
- **config**: Configuration object for the properties panel.
- **historyCommands**: Object for managing undo/redo history.
- **translate**: Translation function.
- **...other props**

### Type Definitions
- **EntryDefinition**: Defines the structure for individual property entries.
- **GroupDefinition**: Defines the structure for grouping property entries.
- **ListItemDefinition**: Defines the structure for items within a list.

### Interfaces
- **HeaderProvider**: Interface for providing header information.
- **PlaceholderProvider**: Interface for providing placeholder content.

### Context Providers
- Setup for various context providers like DescriptionContext, TooltipContext, etc.

### Events
- Documentation on events emitted by the properties panel, such as `elementChanged`, ` சேஞ்ச்`.

### Styling
- Information on how to style the properties panel and its elements.

### Usage Examples
- Code snippets demonstrating how to integrate and use the PropertiesPanel component.
```

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

### TooltipContext

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/AllExports.md

Context providing access to tooltip configurations for entries and a function to get tooltip content for a specific entry ID.

```APIDOC
## TooltipContext

### Description
Context for entry tooltips.

### Context Value
- **tooltip**: An object mapping entry IDs to tooltip configurations ({ [entryId: string]: Function }).
- **getTooltipForId**: A function to retrieve the tooltip content for a given entry ID.
```

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

### DebounceInput Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Features.md

Use the `debounceInput` factory function to create debounced handlers for input changes. The returned function includes `cancel` and `flush` methods.

```javascript
// In your entry component:
const handleInput = debounceInput(300)((value) => {
  updateElement(value);
});

const handleChange = (e) => {
  handleInput(e.target.value); // Debounced call
};
```

```javascript
handleInput.cancel();  // Cancel pending execution
handleInput.flush();   // Execute immediately and clear pending
```

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

### useLayoutState

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Creates persistent state tied to the global layout context. It allows you to get and set values based on a provided path, with an optional default value.

```APIDOC
## useLayoutState

### Description
Create persistent state tied to the global layout context.

### Signature
```javascript
useLayoutState(path: (string | number)[], defaultValue?: any): [state: any, setState: (value: any) => void]
```

### Parameters
#### Path Parameters
- **path** ( (string | number)[] ) - Yes - Array path in layout object (e.g., `['groups', 'general', 'open']`)
- **defaultValue** ( any ) - No - Value if key doesn't exist in layout

### Returns
Returns a tuple `[value, setValue]` where `value` is the current state and `setValue` updates it.

### Usage Example
```javascript
function Group(props) {
  const [open, setOpen] = useLayoutState(['groups', props.id, 'open'], false);
  
  return (
    <div>
      <button onClick={() => setOpen(!open)}>Toggle</button>
      {open && <Content />}
    </div>
  );
}
```
```

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

### Custom CSS Styling for Properties Panel

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/UtilityComponents.md

Examples of overriding default styles for properties panel elements using CSS. This allows for custom theming and appearance adjustments.

```css
.bio-properties-panel-input {
  border: 2px solid #ccc;
  padding: 8px;
}

.bio-properties-panel-input:focus {
  border-color: #0066cc;
}

.bio-properties-panel-entry {
  margin-bottom: 12px;
}
```

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

### Implement Async Validation for Custom Entry

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/errors.md

This example demonstrates asynchronous validation using `useEffect` and `setTimeout` to trigger a server-side validation check after a delay. Errors are reported using `eventBus.fire('propertiesPanel.setErrors')`.

```javascript
import { useEffect } from 'preact/hooks';

function AsyncValidatedEntry(props) {
  const { id, value } = props;
  
  useEffect(() => {
    const validateAsync = async () => {
      try {
        const result = await validateOnServer(value);
        
        if (!result.valid) {
          eventBus.fire('propertiesPanel.setErrors', {
            errors: { [id]: result.error }
          });
        }
      } catch (error) {
        eventBus.fire('propertiesPanel.setErrors', {
          errors: { [id]: 'Validation failed' }
        });
      }
    };
    
    const timeoutId = setTimeout(validateAsync, 500);
    
    return () => clearTimeout(timeoutId);
  }, [value]);
  
  return <input value={value} />; 
}
```

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

### FeelEntry Component

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/EntryComponents.md

Component with support for FEEL (Friendly Enough Expression Language). It requires element, id, label, and functions to get and set the value. Supports various optional props like feel type, debounce, disabled, placeholder, variables, and callbacks.

```javascript
import { FeelEntry } from '@bpmn-io/properties-panel';

type FeelType = 'required' | 'optional' | 'optional-default-enabled' | 'static'

function FeelEntry(props: { 
  element: Object,
  id: string,
  label: string,
  getValue: (element: Object) => string,
  setValue: (element: Object, value: string) => void,
  description?: string,
  feel?: FeelType,
  debounce?: boolean | number,
  disabled?: boolean,
  placeholder?: string,
  variables?: Array<{name: string, type?: string}>,
  onFocus?: Function,
  onBlur?: Function,
  tooltip?: string | Component
}): JSX.Element
```

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

### Integrating Properties Panel with Standalone Panel

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Features.md

Demonstrates setting up the Properties Panel in a standalone mode, including manual configuration for features like debounce input and Feel popup container.

```javascript
import { PropertiesPanel } from '@bpmn-io/properties-panel';

const eventBus = {
  on: (event, callback) => { /* ... */ },
  off: (event, callback) => { /* ... */ },
  fire: (event, context) => { /* ... */ }
};

// Configure features manually
const config = {
  debounceInput: 300,
  propertiesPanel: {
    feelPopupContainer: document.getElementById('popup')
  }
};
```

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

### ErrorsContext Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Use the ErrorsContext to determine if a group of entries has any validation errors. This example checks if any entry ID within the group exists in the errors map.

```javascript
function Group(props) {
  const { errors } = useContext(ErrorsContext);
  const hasErrors = props.entries.some(e => errors[e.id]);
  
  return (
    <div className={hasErrors ? 'has-errors' : ''}>
      {/* render entries */}
    </div>
  );
}
```

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

### Creating a Custom Properties Panel Module

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Features.md

Illustrates the pattern for creating custom modules for the properties panel, including defining services and their dependencies.

```javascript
export default {
  __init__: ['myService'],
  myService: ['type', MyService]
};

class MyService {
  constructor(eventBus, config) {
    this._eventBus = eventBus;
    this._config = config;
  }
}

MyService.$inject = ['eventBus', 'config.propertiesPanel'];
```

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

### PropertiesPanelContext Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Use the PropertiesPanelContext to conditionally trigger auto-show events for entries based on the current element. This example shows a button that calls onShow if the element and its parent exist.

```javascript
function CustomEntry(props) {
  const { element, onShow } = useContext(PropertiesPanelContext);
  
  const handleClick = () => {
    if (element && element.parentElement) {
      onShow();
    }
  };
  
  return <button onClick={handleClick}>Show Parent</button>;
}
```

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

### Build and Test Library

Source: https://github.com/bpmn-io/properties-panel/blob/main/README.md

Builds the library and executes all defined tests. This is a common command for verifying the project's integrity.

```sh
npm run all
```

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

### usePrevious Hook

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/SUMMARY.txt

A custom hook to get the previous value of a state.

```APIDOC
## usePrevious

### Description
A custom hook to get the previous value of a state.

### Signature
`usePrevious(value: any)`

### Parameters
#### Arguments
- **value** (any) - Required - The current value.

### Return Type
`any` - The previous value.

### Source File
`/workspace/home/output/api-reference/Hooks.md`
```

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

### useError Hook

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/AllExports.md

Hook to get a specific error associated with an entry ID.

```javascript
function useError(id: string): any | undefined
```

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

### Firing propertiesPanel.closePopup Event

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Example of firing the 'propertiesPanel.closePopup' event to close an active overlay popup.

```javascript
eventBus.fire('propertiesPanel.closePopup');
```

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

### Accessing FEEL Language Configuration

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Shows how to import and use the FeelLanguageContext to access FEEL parser dialect, built-ins, and dialect configuration.

```javascript
import { FeelLanguageContext } from '@bpmn-io/properties-panel';

function MyComponent() {
  const { parserDialect, builtins, dialect } = useContext(FeelLanguageContext);
}
```

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

### Subscribing to propertiesPanel.setErrors Event

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Example of subscribing to the 'propertiesPanel.setErrors' event to receive and log validation errors.

```javascript
eventBus.on('propertiesPanel.setErrors', ({ errors }) => {
  console.log(errors); // { entryId: errorObject, ... }
});
```

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

### DescriptionContext

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/AllExports.md

Context providing access to descriptions for entries and a function to get a description for a specific entry ID.

```APIDOC
## DescriptionContext

### Description
Context for entry descriptions.

### Context Value
- **description**: An object mapping entry IDs to description functions ({ [entryId: string]: Function }).
- **getDescriptionForId**: A function to retrieve the description for a given entry ID.
```

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

### Creating Custom Contexts

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Illustrates how to create and provide custom contexts alongside the built-in properties panel contexts for advanced use cases.

```APIDOC
## Creating Custom Contexts

For advanced use cases, you can create custom contexts alongside the built-in ones:

```javascript
const CustomContext = createContext({});

<PropertiesPanelContext.Provider value={panelContext}>
  <CustomContext.Provider value={customValue}>
    <YourContent />
  </CustomContext.Provider>
</PropertiesPanelContext.Provider>
```
```

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

### TooltipContext Definition

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/AllExports.md

Defines the context for tooltips, providing access to a tooltip map and a function to get tooltips by ID.

```javascript
Context<{
  tooltip: { [entryId: string]: Function },
  getTooltipForId: Function
}>
```

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

### Initialize Properties Panel with Groups and Header Provider

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/INDEX.md

This snippet demonstrates how to initialize the PropertiesPanel component. It includes defining groups with various entry components like TextFieldEntry and SelectEntry, and configuring a headerProvider to display element metadata.

```javascript
import { PropertiesPanel, TextFieldEntry, SelectEntry } from '@bpmn-io/properties-panel';

const groups = [
  {
    id: 'general',
    label: 'General',
    entries: [
      {
        id: 'name',
        component: TextFieldEntry,
        isEdited: (node) => !!node?.value
      },
      {
        id: 'type',
        component: SelectEntry
      }
    ]
  }
];

<PropertiesPanel
  element={selectedElement}
  groups={groups}
  headerProvider={{
    getElementLabel: (el) => el.name,
    getTypeLabel: (el) => el.$type,
    getElementIcon: (el) => IconComponent
  }}
/>
```

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

### DescriptionContext Definition

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/AllExports.md

Defines the context for descriptions, providing access to a description map and a function to get descriptions by ID.

```javascript
Context<{
  description: { [entryId: string]: Function },
  getDescriptionForId: Function
}>
```

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

### FeelPopup open() Method

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Features.md

Opens the FEEL popup, requiring an entry ID, configuration object, and the source HTML element.

```javascript
open(entryId: string, popupConfig: Object, sourceElement: HTMLElement): void
```

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

### Creating Custom Contexts with React Context API

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Shows how to create and provide a custom context using React's createContext and Context.Provider, alongside the PropertiesPanelContext.

```javascript
const CustomContext = createContext({});

<PropertiesPanelContext.Provider value={panelContext}>
  <CustomContext.Provider value={customValue}>
    <YourContent />
  </CustomContext.Provider>
</PropertiesPanelContext.Provider>
```

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

### Custom Error Display CSS

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/errors.md

Provides CSS examples for custom styling of entries and inputs that have errors, as well as for displaying error messages.

```css
.bio-properties-panel-entry[data-entry-id="name"].error {
  border-left: 3px solid #d32f2f;
  background: #ffebee;
}

.bio-properties-panel-input.has-error {
  border-color: #d32f2f;
  background: #fff5f5;
}

.error-message {
  color: #d32f2f;
  font-size: 12px;
  margin-top: 4px;
}
```

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

### LayoutContextValue Type

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/types.md

Defines the value for the LayoutContext. It provides layout configuration, a function to set the layout, and utilities to get or set layout properties by path.

```javascript
type LayoutContextValue = {
  layout: Object,
  setLayout: (layout: Object) => void,
  getLayoutForKey: (path: string | string[], defaultValue?: any) => any,
  setLayoutForKey: (path: string | string[], value: any) => void
}
```

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

### UtilityComponents.md

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/README.md

Reference for utility components and helpers, including dropdowns, buttons, icons, and CSS class references.

```APIDOC
## Utility Components and Helpers

### Description
A collection of reusable UI components, icons, and utility functions that support the properties panel's functionality and appearance.

### Available Components
- **DropdownButton**: Renders a button that triggers a dropdown menu.
- **HeaderButton**: A button specifically designed for use in headers.
- **SimpleEntry**: A basic component for displaying read-only text.
- **Tooltip**: A component for displaying tooltips on hover.
- **DescriptionEntry**: Displays help text or descriptions for entries.
- **OpenPopupButton**: A button component that triggers a popup.

### Icons
- A set of commonly used icons:
  - **ArrowIcon**
  - **CreateIcon**
  - **DeleteIcon**
  - **ExternalLinkIcon**

### Utilities
- **KeyboardUtils**: Helper functions for keyboard interactions (e.g., `isCmdWithChar`).
- **TranslateFallback**: Provides a fallback mechanism for internationalization (i18n).

### CSS Class Reference
- Documentation of CSS classes used for styling various elements like entries, groups, and the panel itself.

### Custom Styling Examples
- Examples demonstrating how to apply custom styles to components.
```

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

### Subscribing to propertiesPanel.showEntry Event

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Shows how to subscribe to the 'propertiesPanel.showEntry' event, which is fired when an entry needs to be scrolled into view and focused.

```javascript
eventBus.on('propertiesPanel.showEntry', ({ id, focus = false }) => {
  // Entry component should focus its input
});
```

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

### Map Entries to Descriptions

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/configuration.md

Configures descriptions for specific entry IDs, providing context-sensitive help text. The `descriptionConfig` maps entry IDs to functions that return the description string.

```javascript
const descriptionConfig = {
  'name': (id, element) => 'The name uniquely identifies this element',
  'email': (id, element) => `Email must follow RFC 5322 format`,
  'age': (id, element) => `Age in years (0-150)`
};

<PropertiesPanel
  descriptionConfig={descriptionConfig}
  descriptionLoaded={(descriptions) => console.log('Loaded')}
  {...otherProps}
/>
```

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

### EventBus Methods

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Illustrates the available methods on the EventBus instance for subscribing to, unsubscribing from, and firing events.

```javascript
eventBus.on(event: string, callback: Function): Function
eventBus.off(event: string, callback: Function): void
eventBus.fire(event: string, context?: Object): any
```

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

### DescriptionEntry Component

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/UtilityComponents.md

Displays help text below an entry. Use this to provide additional context or instructions for an input field. It requires an ID and the description text, with an optional CSS class name.

```javascript
import { DescriptionEntry } from '@bpmn-io/properties-panel';

<input id="name-input" />
<DescriptionEntry
  id="name-input"
  value="Must be unique within the diagram"
/>
```

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

### Configure Placeholder Provider for Empty/Multiple States

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/configuration.md

Defines custom UI content for when no element is selected or multiple elements are selected. The `placeholderProvider` returns objects with `icon`, `text`, and `secondaryText` for these states.

```javascript
const placeholderProvider = {
  getEmpty: () => ({
    icon: EmptyIcon,
    text: 'No element selected',
    secondaryText: 'Select an element to view its properties'
  }),
  
  getMultiple: () => ({
    icon: MultiIcon,
    text: 'Multiple elements selected',
    secondaryText: 'Select a single element to edit properties'
  })
};

<PropertiesPanel
  placeholderProvider={placeholderProvider}
  {...otherProps}
/>
```

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

### Firing propertiesPanel.openPopup Event

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Demonstrates firing the 'propertiesPanel.openPopup' event to open an overlay popup with specified details.

```javascript
eventBus.fire('propertiesPanel.openPopup', {
  entryId: 'myEntry',
  element: editorElement,
  label: 'FEEL Editor',
  sourceElement: inputElement
});
```

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

### Access DescriptionContext

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Access description text for entries using the DescriptionContext. Import DescriptionContext and useContext.

```javascript
import { DescriptionContext } from '@bpmn-io/properties-panel';

function MyComponent() {
  const { description, getDescriptionForId } = useContext(DescriptionContext);
}
```

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

### useError Usage Example

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Demonstrates how to use the useError hook to conditionally apply an error class to an input element and display an error message if a validation error exists for the entry.

```javascript
function MyEntry(props) {
  const error = useError(props.id);
  
  return (
    <div className={error ? 'has-error' : ''}>
      <input />
      {error && <span className="error">{error.message}</span>}
    </div>
  );
}
```

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

### Accessing Properties Panel Contexts

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Demonstrates how to import and use various React contexts provided by the properties panel library to access shared state and functionalities like the event bus or element details.

```javascript
import {
  PropertiesPanelContext,
  ErrorsContext,
  DescriptionContext,
  TooltipContext,
  LayoutContext,
  EventContext,
  FeelLanguageContext
} from '@bpmn-io/properties-panel';

// Usage:
const { element, onShow } = useContext(PropertiesPanelContext);
const { errors } = useContext(ErrorsContext);
const { eventBus } = useContext(EventContext);
```

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

### Clear Errors on Input Focus

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/errors.md

This example demonstrates clearing an error associated with an input field when the user focuses on it, using `onFocus` event and `eventBus.fire('propertiesPanel.setErrors')` to update the error state.

```javascript
function EntryWithErrorClearing(props) {
  const { id } = props;
  const { eventBus } = useContext(EventContext);
  
  const handleFocus = () => {
    // Clear error when user starts typing
    const errors = useErrors();
    if (errors[id]) {
      const { [id]: removed, ...rest } = errors;
      eventBus.fire('propertiesPanel.setErrors', { errors: rest });
    }
  };
  
  return (
    <input
      onFocus={handleFocus}
      value={props.value}
    />
  );
}
```

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

### FEEL Entry Configuration

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/configuration.md

Configure a FEEL (Friendly Enough Expression Language) entry. Options include specifying if FEEL is required or optional, providing available variables, enabling single-line editing, and setting placeholder text.

```javascript
{
  ...commonProps,
  feel?: 'required' | 'optional' | 'optional-default-enabled' | 'static',
  variables?: Array<Variable>,
  singleLine?: boolean,
  placeholder?: string,
}
```

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

### DescriptionContext

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/SUMMARY.txt

Context provider for managing descriptions in the properties panel.

```APIDOC
## DescriptionContext

### Description
Context provider for managing descriptions in the properties panel.

### Usage
Wrap your application or relevant part with `DescriptionContext.Provider`.

### Value
Provides access to description-related state and functions.

### Source File
`/workspace/home/output/api-reference/Contexts.md`
```

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

### FeelCheckboxEntry Component

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/EntryComponents.md

A checkbox component that can be toggled to a FEEL expression. It requires element, id, label, and functions to get and set the value. Optional props include feel type and disabled.

```javascript
import { FeelCheckboxEntry } from '@bpmn-io/properties-panel';

function FeelCheckboxEntry(props: { 
  element: Object,
  id: string,
  label: string,
  getValue: (element: Object) => boolean | string,
  setValue: (element: Object, value: boolean | string) => void,
  feel?: 'required' | 'optional' | 'optional-default-enabled',
  disabled?: boolean,
  tooltip?: string | Component
}): JSX.Element
```

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

### Set Validation Errors

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/configuration.md

Defines a function `handleSetErrors` to dispatch validation errors to the properties panel via an event. An example `errors` object demonstrates the expected structure for different error types.

```javascript
const handleSetErrors = (errors) => {
  eventBus.fire('propertiesPanel.setErrors', { errors });
};

// Example errors object:
const errors = {
  'name': 'Name is required',
  'age': 'Age must be between 0 and 150',
  'email': { message: 'Invalid email format' }
};
```

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

### DescriptionEntry

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/EntryComponents.md

A read-only text display component for showing informational content.

```APIDOC
## DescriptionEntry

### Description
Text display for read-only information.

### Props
- **id** (string): Unique identifier for the entry.
- **label** (string, optional): The display label for the description.
- **value** (string): The text content to display.
```

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

### TemplatingEntry Component

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/EntryComponents.md

Component with expression templating support. It requires element, id, label, and functions to get and set the value. Optional props include description, debounce, disabled, placeholder, and callbacks.

```javascript
import { TemplatingEntry } from '@bpmn-io/properties-panel';

function TemplatingEntry(props: { 
  element: Object,
  id: string,
  label: string,
  getValue: (element: Object) => string,
  setValue: (element: Object, value: string) => void,
  description?: string,
  debounce?: boolean | number,
  disabled?: boolean,
  placeholder?: string,
  onFocus?: Function,
  onBlur?: Function
}): JSX.Element
```

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

### Using FEEL Language Context in Editor

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Demonstrates passing FEEL language context properties (parserDialect, builtins) to an Editor component.

```javascript
function FeelEditor(props) {
  const feelContext = useContext(FeelLanguageContext);
  
  return (
    <Editor
      parserDialect={feelContext.parserDialect}
      builtins={feelContext.builtins}
    />
  );
}
```

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

### JsonEditorEntry Component

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/EntryComponents.md

A code editor component specifically for JSON content. It requires element, id, label, and functions to get and set the JSON value. Debounce, disabled, onFocus, and onBlur are optional.

```javascript
import { JsonEditorEntry } from '@bpmn-io/properties-panel';

function JsonEditorEntry(props: { 
  element: Object,
  id: string,
  label: string,
  getValue: (element: Object) => Object,
  setValue: (element: Object, value: Object) => void,
  description?: string,
  debounce?: boolean | number,
  disabled?: boolean,
  onFocus?: Function,
  onBlur?: Function
}): JSX.Element
```

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

### useTooltipContext

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Access tooltip content for entries. It retrieves either a string or a React component for tooltips based on the entry ID and element context.

```APIDOC
## useTooltipContext

### Description
Access tooltip content for entries.

### Signature
```javascript
useTooltipContext(id: string, element: Object): string | Component | undefined
```

### Parameters
#### Path Parameters
- **id** ( string ) - Yes - Entry ID for tooltip
- **element** ( Object ) - Yes - Current element

### Returns
Returns tooltip string or component, or undefined if not configured.
```

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

### Select Configuration

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/configuration.md

Configure a select entry, which requires an array of options. Each option can have a value, label, and optional disabled state or nested children for optgroups.

```javascript
{
  ...commonProps,
  options: Array<Option>  // Select options
}
```

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

### Auto-clear Errors on Valid Input

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/errors.md

This example shows a text field component that automatically clears its error state when the input value becomes valid and is no longer empty. It uses `props.onChange` and `eventBus.fire('propertiesPanel.setErrors')`.

```javascript
function TextFieldWithAutoClear(props) {
  const error = useError(props.id);
  
  const handleInput = (value) => {
    props.onChange(value);
    
    // Auto-clear error if value becomes valid
    if (error && value.trim() !== '') {
      const errors = useErrors();
      const { [props.id]: removed, ...rest } = errors;
      eventBus.fire('propertiesPanel.setErrors', { errors: rest });
    }
  };
  
  return <input value={props.value} onInput={handleInput} />; 
}
```

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

### Use Show Entry Event Hook

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Hooks.md

Listens for the 'propertiesPanel.showEntry' event and automatically focuses the input when the event ID matches. Selects all text if the input has a `.select()` method and scrolls it into view.

```javascript
function TextInput(props) {
  const ref = useShowEntryEvent(props.id);
  
  return (
    <input
      ref={ref}
      value={props.value}
      onChange={(e) => props.onChange(e.target.value)}
    />
  );
}
```

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

### Integrate Server-Side Validation

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/errors.md

This snippet provides a function `validateOnServer` to perform backend validation via a POST request and an example of how to use this function within a `useEffect` hook to update the properties panel with server-side errors.

```javascript
async function validateOnServer(element) {
  try {
    const response = await fetch('/api/validate', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(element)
    });
    
    const result = await response.json();
    
    return {
      valid: result.isValid,
      errors: result.errors || {}
    };
  } catch (error) {
    return {
      valid: false,
      errors: { '_global': 'Validation service unavailable' }
    };
  }
}

// Use in panel
useEffect(() => {
  validateOnServer(element).then(result => {
    if (!result.valid) {
      eventBus.fire('propertiesPanel.setErrors', {
        errors: result.errors
      });
    }
  });
}, [element]);
```

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

### FeelPopup Configuration

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Features.md

Configure the FEEL popup's container and link generation via `config.propertiesPanel`. The `getFeelPopupLinks` function can provide custom links for the popup header.

```javascript
const config = {
  propertiesPanel: {
    feelPopupContainer: document.getElementById('popup-container'),
    getFeelPopupLinks: (type) => [
      { label: 'Documentation', href: 'https://docs.example.com' }
    ]
  }
};
```

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

### Accessing EventBus from EventContext

Source: https://github.com/bpmn-io/properties-panel/blob/main/_autodocs/api-reference/Contexts.md

Shows how to import and use the EventContext to gain access to the eventBus instance within a component.

```javascript
import { EventContext } from '@bpmn-io/properties-panel';

function MyComponent() {
  const { eventBus } = useContext(EventContext);
}
```