Property Editor Component

The Property Editor component provides a reusable interface for editing arbitrary JavaScript property objects. It automatically generates appropriate editors based on property types and can be customized with metadata.

Usage

<qds-property-editor 
  label="User Settings" 
  expanded>
</qds-property-editor>

<script>
  const editor = document.querySelector('qds-property-editor');
  
  // Set the object to edit
  editor.target = {
    name: "John Doe",
    age: 30,
    isActive: true,
    startDate: new Date("2023-01-15"),
    favoriteColor: getComputedStyle(document.documentElement).getPropertyValue('--theme-accent-primary').trim()
  };
  
  // Optionally provide metadata to customize the editors
  editor.metadata = {
    name: {
      displayName: "Full Name",
      description: "The user's full name",
      placeholder: "Enter full name"
    },
    age: {
      displayName: "Age",
      type: "number",
      min: 0,
      max: 120
    },
    isActive: {
      displayName: "Active Status"
    },
    startDate: {
      displayName: "Start Date",
      type: "date"
    },
    favoriteColor: {
      displayName: "Favorite Color",
      type: "color"
    }
  };
  
  // Listen for changes
  editor.addEventListener('change', (event) => {
    console.log('Property changed:', event.detail.property);
    console.log('New value:', event.detail.value);
    console.log('Updated object:', event.detail.target);
  });
</script>

Attributes

Attribute	Type	Default	Description
label	String	“Properties”	The heading text displayed at the top of the property editor
expanded	Boolean	true	Whether the property editor is initially expanded or collapsed

Properties

Property	Type	Default	Description
target	Object	{}	The JavaScript object being edited
metadata	Object	{}	Optional metadata to customize property editors

Metadata Structure

The metadata object allows you to customize how each property is displayed and edited:

{
  propertyName: {
    displayName: "User-friendly Name",  // Display label (default: formatted property name)
    description: "Tooltip text",        // Shown on hover (default: "")
    type: "string",                     // Editor type (default: based on JS type)
    // Additional attributes based on type:
    
    // For type: "number"
    min: 0,                             // Minimum value
    max: 100,                           // Maximum value
    step: 5,                            // Step increment
    
    // For type: "select" 
    options: [                          // Dropdown options
      { value: "option1", label: "Option 1" },
      { value: "option2", label: "Option 2" }
    ],
    
    // For type: "string"
    placeholder: "Enter value...",      // Placeholder text
    pattern: "[A-Za-z]+"                // Validation pattern
  }
}

If metadata for a property is not provided, the component automatically creates default metadata based on the JavaScript type of the property value.

type vs valueRole

A field’s type and its optional valueRole answer two different questions:

• type — the primitive/editor/storage shape: how the value is stored and which built-in control edits it (string, number, boolean, date, color, select, textarea, typography).
• valueRole — an optional, host-agnostic semantic hint: what the value means, independent of how it is stored. It carries no behavior in QDS — it is metadata only.

For example, an image URL and a link URL are both stored as plain strings (type: 'string'), but they mean different things:

{
  mediaSrc: { type: 'string', valueRole: 'image-asset' },
  primaryHref: { type: 'string', valueRole: 'link-target' }
}

valueRole lets a host application attach a role-specific editor or picker once per role (e.g. one image picker for every image-asset field) instead of patching individual field names. QDS defines a few generic roles for its built-in blocks (image-asset, link-target); the field is an open string, so hosts may define their own. See the content-blocks README for the built-in roles.

Supported Editor Types

The component automatically selects appropriate editors based on the property type:

Type	Editor	Default Type For
string	Text input	Strings, null, undefined
number	Number input	Numbers
boolean	Checkbox	Booleans
date	Date picker	Date objects
color	Color picker	Strings matching color format
select	Dropdown	When options array is provided

Events

Event	Detail	Description
change	{ property, value, target }	Fired when any property value changes

CSS Parts

Part	Description
editor	The main container element
header	The collapsible header element
title	The header title text
expander	The expand/collapse indicator
container	The container for property editors

Examples

Basic Property Editing

<qds-property-editor id="basic-editor"></qds-property-editor>

<script>
  document.getElementById('basic-editor').target = {
    firstName: "John",
    lastName: "Doe",
    age: 30
  };
</script>

Custom Metadata with Validation

<qds-property-editor id="advanced-editor" label="Product Details"></qds-property-editor>

<script>
  const editor = document.getElementById('advanced-editor');
  
  editor.target = {
    name: "Widget Pro",
    price: 99.99,
    inStock: true,
    category: "gadgets"
  };
  
  editor.metadata = {
    name: {
      displayName: "Product Name",
      description: "Enter the full product name"
    },
    price: {
      displayName: "Price (USD)",
      type: "number",
      min: 0.01,
      step: 0.01
    },
    inStock: {
      displayName: "Currently In Stock"
    },
    category: {
      displayName: "Product Category",
      type: "select",
      options: [
        { value: "gadgets", label: "Gadgets" },
        { value: "accessories", label: "Accessories" },
        { value: "software", label: "Software" }
      ]
    }
  };
</script>

Accessibility

The Property Editor component includes the following accessibility features:

• Proper keyboard navigation support
• ARIA attributes for expandable sections
• Explicit labels for all form controls
• Focus management
• Sufficient color contrast
• Touch-friendly targets for mobile use

Browser Support

This component is compatible with all modern browsers, including:

• Chrome
• Firefox
• Safari
• Edge