@servicenow/sdk-build-plugins 4.1.1 → 4.3.0

package/src/column-plugin.ts

@@ -88,7 +88,7 @@ export const ColumnPlugin = Plugin.create({
                 value: `sys_choice_${record.get('name').getValue()}_${record.get('element').getValue()}`,
             }),
             async toFile(choiceSet, { config, descendants, transform }) {
-                if (config.tableOutputFormat === 'bootstrap') {
+                if (config.tableOutputFormat === 'bootstrap' && config.type === 'package') {
                     // Defer to table plugin
                     return { success: false }
                 }
@@ -96,7 +96,7 @@ export const ColumnPlugin = Plugin.create({
                 const tableName = choiceSet.get('name').asString().getValue()
                 const elementName = choiceSet.get('element').asString().getValue()
                 const xml = create().ele('record_update')
-                const root = xml.ele('sys_choice_set', { table: tableName })
+                const root = xml.ele('sys_choice_set', { table: tableName, field: elementName })
                 descendants.query('sys_choice').forEach((choice) => {
                     const child = root.ele('sys_choice', { action: choice.getAction() })
                     child.ele('sys_id').txt(choice.getId().getValue())
@@ -186,18 +186,34 @@ export const ColumnPlugin = Plugin.create({
                             properties: column.transform(({ $ }) => ({
                                 name: $.from('table'),
                                 element: $.from('name'),
-                                internal_type: $.val(columnType),
+                                internal_type: $.from('isFullUTF8')
+                                    .map((isFullUTF8) =>
+                                        isFullUTF8?.isBoolean() &&
+                                        isFullUTF8.asBoolean().getValue() &&
+                                        columnType === 'string'
+                                            ? 'string_full_utf8'
+                                            : columnType
+                                    )
+                                    .def(columnType),
                                 active: $.toBoolean().def(true),
                                 array: $.toBoolean().def(false),
-                                attributes: $.map((attributes) => {
-                                    if (!attributes.isObject()) {
-                                        return undefined
-                                    }
-                                    const attributesObj = attributes.asObject().getValue()
-                                    return Object.entries(attributesObj)
-                                        .map(([key, value]) => `${key}=${value}`)
-                                        .join(',')
-                                }).def(''),
+                                attributes: $.from('attributes', 'scale', 'script')
+                                    .map((attributes, scale, script) => {
+                                        const attrs = attributes?.isObject() ? attributes.asObject().getValue() : {}
+
+                                        // Add special parameters to attributes
+                                        if (scale?.isNumber()) {
+                                            attrs['scale'] = scale.asNumber().getValue()
+                                        }
+                                        if (script?.isString()) {
+                                            attrs['script'] = script.asString().getValue()
+                                        }
+
+                                        return Object.entries(attrs)
+                                            .map(([key, value]) => `${key}=${value}`)
+                                            .join(',')
+                                    })
+                                    .def(''),
                                 audit: $.toBoolean().def(false),
                                 reference_cascade_rule: $.from('cascadeRule'),
                                 default_value: $.from('default'),
@@ -267,19 +283,42 @@ export const ColumnPlugin = Plugin.create({
                                         ? dynamicValueDefinitions.asObject().get('field').ifString()
                                         : undefined
                                 ),
-                                dependent: $.from('dynamicValueDefinitions').map((dynamicValueDefinitions) => {
-                                    if (
-                                        dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() !==
-                                        'dependent_field'
-                                    ) {
+
+                                dependent: $.from('dependent', 'dynamicValueDefinitions').map(
+                                    (dependent, dynamicValueDefinitions) => {
+                                        // New direct approach (DocumentIdColumn, TemplateValueColumn, FieldListColumn)
+                                        if (dependent?.isString()) {
+                                            return dependent.asString().getValue()
+                                        }
+
+                                        if (dependent?.isObject()) {
+                                            diagnostics.warn(
+                                                dependent.getOriginalNode(),
+                                                `Passing a TableNameColumn object to 'dependent' is deprecated and will not work as expected. Pass the field name as a string instead.`
+                                            )
+                                        }
+
+                                        // Legacy approach via dynamicValueDefinitions
+                                        if (
+                                            dynamicValueDefinitions?.ifObject()?.get('type').ifString()?.getValue() ===
+                                            'dependent_field'
+                                        ) {
+                                            const dynamicValueObject = dynamicValueDefinitions
+                                                .asObject()
+                                                .withAliasedKeys(calculationAliases)
+                                            generateDeprecatedDiagnostics(dynamicValueObject, diagnostics)
+                                            diagnostics.warn(
+                                                dynamicValueDefinitions.getOriginalNode(),
+                                                `Using 'dynamicValueDefinitions: { type: "dependent_field" }' is deprecated. ` +
+                                                    `Use 'dependent: "field_name"' directly on the column instead.`
+                                            )
+
+                                            return dynamicValueObject.get('columnName').ifString()?.getValue()
+                                        }
+
                                         return undefined
                                     }
-                                    const dynamicValueObject = dynamicValueDefinitions
-                                        .asObject()
-                                        .withAliasedKeys(calculationAliases)
-                                    generateDeprecatedDiagnostics(dynamicValueObject, diagnostics)
-                                    return dynamicValueObject.get('columnName').ifString()
-                                }),
+                                ),
                                 dependent_on_field: $.from('dynamicValueDefinitions').map((dynamicValueDefinitions) => {
                                     if (
                                         dynamicValueDefinitions.ifObject()?.get('type').ifString()?.getValue() !==
@@ -316,7 +355,20 @@ export const ColumnPlugin = Plugin.create({
                                     )
                                     .def(getDefaultMaxLength(columnType)),
                                 primary: $.toBoolean().def(false),
-                                read_only: $.from('readOnly').toBoolean().def(false),
+                                read_only: $.from('readOnly', 'readOnlyOption')
+                                    .map((readOnly, readOnlyOption) => {
+                                        const readOnlyValue = readOnly.ifBoolean()?.getValue()
+                                        const readOnlyOptionValue = readOnlyOption.ifString()?.getValue()
+                                        if (readOnlyValue === false && readOnlyOptionValue) {
+                                            diagnostics.error(
+                                                readOnly,
+                                                `readOnly cannot be false with readOnlyOption ${readOnlyOptionValue}.`
+                                            )
+                                        }
+                                        return readOnlyValue ?? !!readOnlyOptionValue
+                                    })
+                                    .def(false),
+                                read_only_option: $.from('readOnlyOption'),
                                 reference: $.from('referenceTable'),
                                 spell_check: $.from('spellCheck').toBoolean().def(false),
                                 table_reference: $.from('tableReference').toBoolean().def(false),
@@ -337,7 +389,10 @@ export function columnToCallExpression(
     column: Record,
     related: { choices: Record[]; documentation: Record[] }
 ): CallExpressionShape {
-    const callExpression = COLUMN_TYPE_TO_API[column.get('internal_type').asString().getValue()] ?? GenericColumn.name
+    const internalType = column.get('internal_type').asString().getValue()
+    // Normalize string_full_utf8 to string for column type lookup
+    const normalizedType = internalType === 'string_full_utf8' ? 'string' : internalType
+    const callExpression = COLUMN_TYPE_TO_API[normalizedType] ?? GenericColumn.name
     const { choices, documentation } = related
     return new CallExpressionShape({
         source: column,
@@ -351,7 +406,7 @@ export function columnToCallExpression(
                         if (!attributes.isString()) {
                             return undefined
                         }
-                        const result = {}
+                        const result: { [key: string]: string | boolean } = {}
                         attributes
                             .toString()
                             .getValue()
@@ -361,18 +416,61 @@ export function columnToCallExpression(
                                     return
                                 }
                                 const [key, value] = attr.split('=').map((s) => s.trim())
+                                // Filter out special parameters that have their own fields
+                                if (key === 'scale' || key === 'script') {
+                                    return
+                                }
+                                if (!key || value === undefined) {
+                                    return
+                                }
                                 if (value === 'true') {
-                                    result[key!] = true
+                                    result[key] = true
                                 } else if (value === 'false') {
-                                    result[key!] = false
+                                    result[key] = false
                                 } else {
-                                    result[key!] = value
+                                    result[key] = value
                                 }
                             })
                         return result
                     }).def({
                         edge_encryption_enabled: true,
                     }),
+                    // Extract special parameters from attributes
+                    scale: $.from('attributes').map((attributes) => {
+                        if (!attributes.isString()) {
+                            return undefined
+                        }
+                        const scaleMatch = attributes
+                            .asString()
+                            .getValue()
+                            .match(/scale=([^,]+)/)
+                        return scaleMatch ? Number(scaleMatch[1]) : undefined
+                    }),
+                    script: $.from('attributes').map((attributes) => {
+                        if (!attributes.isString()) {
+                            return undefined
+                        }
+                        const scriptMatch = attributes
+                            .asString()
+                            .getValue()
+                            .match(/script=([^,]+)/)
+                        return scriptMatch ? scriptMatch[1] : undefined
+                    }),
+                    source_table: $.from('attributes').map((attributes) => {
+                        if (!attributes.isString()) {
+                            return undefined
+                        }
+                        const sourceTableMatch = attributes
+                            .asString()
+                            .getValue()
+                            .match(/source_table=([^,]+)/)
+                        return sourceTableMatch ? sourceTableMatch[1] : undefined
+                    }),
+                    isFullUTF8: $.from('internal_type').map((internalType) =>
+                        internalType?.isString() && internalType.asString().getValue() === 'string_full_utf8'
+                            ? true
+                            : undefined
+                    ),
                     audit: $.toBoolean().def(false),
                     cascadeRule: $.from('reference_cascade_rule').def(''),
                     columnType: callExpression === GenericColumn.name ? $.from('internal_type') : $.val(undefined),
@@ -456,8 +554,8 @@ export function columnToCallExpression(
                             return dropdownIndex !== -1 ? choiceDropdown[dropdownIndex] : undefined
                         })
                         .def('none'),
-                    dynamicValueDefinitions: $.from('calculation', 'choice_table', 'choice_field', 'dependent').map(
-                        (calculation, choiceTable, choiceField, dependent) => {
+                    dynamicValueDefinitions: $.from('calculation', 'choice_table', 'choice_field').map(
+                        (calculation, choiceTable, choiceField) => {
                             if (
                                 calculation.ifString()?.getValue() &&
                                 calculation.asString().getValue() !== DEFAULT_COLUMN_CALCULATION
@@ -477,18 +575,18 @@ export function columnToCallExpression(
                                     field: choiceField.asString().getValue(),
                                 }
                             }
-                            if (dependent.ifString()?.getValue()) {
-                                return new ObjectShape({
-                                    source: dependent,
-                                    properties: {
-                                        type: 'dependent_field',
-                                        columnName: dependent.asString().getValue(),
-                                    },
-                                }).withAliasedKeys(calculationAliases)
-                            }
+
                             return undefined
                         }
                     ),
+                    // Direct dependent parameter for DocumentIdColumn, TemplateValueColumn, and FieldListColumn
+                    dependent: $.from('dependent').map((dependent) => {
+                        if (dependent?.isString()) {
+                            const value = dependent.asString().getValue()
+                            return value !== '' ? value : undefined
+                        }
+                        return undefined
+                    }),
                     elementReference: $.from('element_reference').toBoolean().def(false),
                     functionDefinition: $.from('function_definition').def(''),
                     label:
@@ -525,6 +623,7 @@ export function columnToCallExpression(
                         .def(getDefaultMaxLength(column.get('internal_type').asString().getValue())),
                     primary: $.toBoolean().def(false),
                     readOnly: $.from('read_only').toBoolean().def(false),
+                    readOnlyOption: $.from('read_only_option').def(''),
                     referenceTable: $.from('reference').def(''),
                     referenceFloats: $.from('reference_floats').toBoolean().def(false),
                     referenceKey: $.from('reference_key').def(''),
@@ -581,6 +680,9 @@ export function isDefaultDocumentation(columnName: string, documentation: Record
         // TODO make default language configurable
         language: 'en',
     }
+    if ('sys_name' in doc) {
+        defaultRecord['sys_name'] = label
+    }
     const optionalFields = ['hint', 'help', 'url', 'url_target', 'sys_policy'] as const
     optionalFields.forEach((field) => {
         if (field in doc) {

package/src/dashboard/dashboard-component-property-defaults.ts

@@ -0,0 +1,277 @@
+import isEmpty from 'lodash/isEmpty'
+import isEqual from 'lodash/isEqual'
+
+export const DEFAULT_PROPERTY_VALUES = {
+    allowAdditionalGroupByPerMetric: false,
+    allowChangeDateRange: false,
+    scoreIcon: '',
+    applyDateRange: false,
+    autoAggregatePeriods: false,
+    bareBorder: false,
+    cacheExpirationTime: 0,
+    chartVariation: 'stacked',
+    dataLabelPosition: 'middle',
+    dataLabelsType: 'both',
+    dateFormat: 'default',
+    disableTooltip: false,
+    emptyStateAlignment: 'vertical-centered',
+    emptyStateContent: 'There are no scores available for the selected criteria. Contact your admin for more info.',
+    emptyStateHeading: 'No data available.',
+    emptyStateHeadingLevel: 3,
+    emptyStateIllustration: 'no-data',
+    enableAddZerosAtApi: true,
+    enableClickAndStay: false,
+    enableCustomEmptyState: false,
+    enableDrilldown: true,
+    enableRealTimeUpdate: false,
+    extensionType: 'step',
+    filterConfigurations: '@state.parFilters',
+    followFilters: true,
+    freezeFirstColumn: true,
+    freezeFooter: false,
+    freezeHeader: true,
+    gaugeArcAngle: '180',
+    headerTitleAlignment: 'start',
+    headingLevel: 2,
+    headingPosition: 'top',
+    hideDevSettings: false,
+    hideMatrixAggregate: false,
+    hideYAxis0: false,
+    hideYAxis1: false,
+    hideYAxis2: false,
+    hideYAxis3: false,
+    hideYAxis4: false,
+    iconStyle: 'background',
+    legendExpandToFit: false,
+    legendHorizontalAlignment: 'center',
+    legendPosition: 'bottom',
+    lineClamp: 1,
+    lineStrokeWidth: '2',
+    mapSysId: '93b8a3a2d7101200bd4a4ebfae61033a',
+    minValue: 0,
+    newReporting: false,
+    numberOfPeriods: 3,
+    period: 'M',
+    registerOrientation: 'horizontal',
+    registerPosition: 'bottom',
+    scoreAlignment: 'start',
+    scoreLabel: 'none',
+    scoreSize: 'auto',
+    scoreType: 'latest',
+    showAbsolutePeriod: false,
+    showAdditionalGroupBySelector: false,
+    showAlternateColumnColors: false,
+    showAlternateRowColors: true,
+    showBorder: true,
+    showCacheTime: true,
+    showChange: false,
+    showChangeFrom: 'previous',
+    showChangePercentage: false,
+    showClosestSeriesOnHover: true,
+    showColumnAggregate: true,
+    showColumnDividers: true,
+    showComment: false,
+    showConfidenceBand: false,
+    showContinuousLine: true,
+    showDataLabels: false,
+    showDataPassthrough: false,
+    showDataTable: false,
+    showDateRangeByDefault: false,
+    showExportOptions: true,
+    showFilterAsSeparateSeries: false,
+    showFilterIcon: true,
+    showFirstGroupAggregate: false,
+    showForecast: false,
+    showForecastRange: false,
+    showGapPercentage: false,
+    showHeader: true,
+    showHeaderSeparator: false,
+    showLabelFirst: false,
+    showLegend: true,
+    showLegendValue: false,
+    showLoadingIndicator: false,
+    showMarkers: false,
+    showMaximumRange: false,
+    showMetricLabel: false,
+    showOverlappingLabels: false,
+    showPercentageOfTotalInTooltip: true,
+    showPivotExpanded: true,
+    showRangeLabels: false,
+    showRangeLimit: true,
+    showRefresh: true,
+    showRegister: true,
+    showRegisterOnSameLine: false,
+    showRegisterPercentage: false,
+    showRegisterValue: false,
+    showRowAggregate: true,
+    showRowDividers: false,
+    showScoreDate: false,
+    showScoreUpdateTime: false,
+    showSecondGroupAggregate: false,
+    showSparkline: false,
+    showStackedValues: 'none',
+    showSubAggregate: true,
+    showTarget: false,
+    showThreshold: false,
+    showTotalAggregate: false,
+    showTrend: false,
+    showXGrid: false,
+    showYGrid: true,
+    showZero: false,
+    sortByOrder: 'desc',
+    sparklineStyle: 'area',
+    truncateColumnHeader: true,
+    truncateFirstColumn: true,
+    truncationType: 'end',
+    useCurrentDateForEnd: false,
+    useDataCache: false,
+    useRelativeScoreTime: false,
+    valueLabelSize: 'md',
+    wrapColumnHeader: false,
+    wrapElements: false,
+    wrapTitle: false,
+    xAxisHidden: false,
+    xAxisMaxLabelSize: 100,
+    xAxisTruncationType: 'end',
+    xAxisWrapLabels: false,
+    yAxis0Position: 'left',
+    yAxis1Position: 'right',
+    yAxis2Position: 'right',
+    yAxis3Position: 'right',
+    yAxis4Position: 'right',
+    yAxisHidden: false,
+    yAxisPosition: 'bottom',
+    yAxisShowGrid: true,
+    yAxisStyle: 'clean',
+    colorConfig: {
+        type: 'default',
+    },
+    userInfo: '@context.session.user',
+}
+
+export const RESTRICTED_PROPERTIES = ['componentId', 'dataPassThrough', 'sharedContext', 'configVersion']
+
+const DEFAULT_NUMBER_FORMAT = {
+    customFormat: false,
+}
+
+/**
+ * Properties to omit from nested structures.
+ * Key = array property name, Value = array of property names to omit from items
+ */
+type OmitConfig = string[] | Record<string, string[]>
+
+const OMIT_DEEP_PATHS: Record<string, OmitConfig> = {
+    dataSources: ['allowRealTime', 'isDatabaseView', 'preferredVisualizations', 'dataCategories'],
+    metrics: ['numberFormat'],
+    groupBy: {
+        groupBy: ['isRange', 'isChoice', 'isPaBucket'],
+    },
+}
+
+/**
+ * Omits deep properties from an object
+ */
+function omitDeepProperties(obj: unknown): unknown {
+    if (!obj || typeof obj !== 'object') {
+        return obj
+    }
+
+    if (Array.isArray(obj)) {
+        return obj.map(omitDeepProperties)
+    }
+
+    const result: Record<string, unknown> = {}
+
+    for (const [key, value] of Object.entries(obj)) {
+        const omitConfig = OMIT_DEEP_PATHS[key]
+
+        if (Array.isArray(value) && omitConfig) {
+            if (Array.isArray(omitConfig)) {
+                // Omit specified properties from each array item
+                result[key] = value.map((item) => {
+                    if (!item || typeof item !== 'object') {
+                        return item
+                    }
+
+                    const filtered: Record<string, unknown> = {}
+                    for (const [itemKey, itemValue] of Object.entries(item)) {
+                        if (omitConfig.includes(itemKey)) {
+                            // Special case: keep numberFormat if it's not default
+                            if (itemKey === 'numberFormat' && key === 'metrics') {
+                                if (itemValue && !isEqual(itemValue, DEFAULT_NUMBER_FORMAT)) {
+                                    filtered[itemKey] = omitDeepProperties(itemValue)
+                                }
+                            }
+                            continue
+                        }
+                        filtered[itemKey] = omitDeepProperties(itemValue)
+                    }
+                    return filtered
+                })
+            } else if (typeof omitConfig === 'object') {
+                // Handle nested config (e.g., groupBy.groupBy)
+                result[key] = value.map((item) => {
+                    if (!item || typeof item !== 'object') {
+                        return item
+                    }
+
+                    const filtered: Record<string, unknown> = {}
+                    for (const [itemKey, itemValue] of Object.entries(item)) {
+                        const nestedConfig = omitConfig[itemKey]
+
+                        if (Array.isArray(itemValue) && Array.isArray(nestedConfig)) {
+                            // Process nested array
+                            filtered[itemKey] = itemValue.map((nestedItem) => {
+                                if (!nestedItem || typeof nestedItem !== 'object') {
+                                    return nestedItem
+                                }
+
+                                const nestedFiltered: Record<string, unknown> = {}
+                                for (const [nestedKey, nestedValue] of Object.entries(nestedItem)) {
+                                    if (!nestedConfig.includes(nestedKey)) {
+                                        nestedFiltered[nestedKey] = omitDeepProperties(nestedValue)
+                                    }
+                                }
+                                return nestedFiltered
+                            })
+                        } else {
+                            filtered[itemKey] = omitDeepProperties(itemValue)
+                        }
+                    }
+                    return filtered
+                })
+            }
+        } else if (value && typeof value === 'object') {
+            const filtered = omitDeepProperties(value)
+            if (!isEmpty(filtered)) {
+                result[key] = filtered
+            }
+        } else {
+            result[key] = value
+        }
+    }
+
+    return result
+}
+
+/**
+ * Removes properties from an object that match their default values
+ */
+export function removeRestrictedValues(props: object): unknown {
+    if (!props) {
+        return props
+    }
+
+    const filtered: Record<string, unknown> = {}
+
+    for (const [key, value] of Object.entries(props)) {
+        if (RESTRICTED_PROPERTIES.find((prop) => prop === key)) {
+            continue
+        }
+
+        filtered[key] = value
+    }
+
+    return omitDeepProperties(filtered)
+}

package/src/dashboard/dashboard-component-resolver.ts

@@ -0,0 +1,69 @@
+/**
+ * Mapping of human-readable component names (kebab-case) to their sys_ids
+ */
+const COMPONENT_NAME_TO_SYSID: Record<string, string> = {
+    area: 'aba8630dc2ccc9b3c1774af1b6820696',
+    boxplot: 'c5d01636ff2602109bd2ffffffffff0a',
+    bubble: '50dbc52a13c8b4691f7c60e0246bf28c',
+    'calendar-report': '259e0221ff18a75c5f5f0fb28fa5d32f',
+    column: '2bd5dc19a7ad083941b7c992a966dd78',
+    'compatibility-mode-widget': '0805a7bf91a93efbdf0a975b38b01051',
+    dial: '63f050cf050137731a828878839e0b33',
+    donut: 'a2b0596cec6b9d49dd1ff9bf76b5084b',
+    gauge: '037bd8ea3013833fd049186779528b70',
+    geomap: '9c8c44bd78fe5918950e0db8e286211d',
+    heading: '1f6e0643eca7a637e36bd7833549ec9e',
+    heatmap: 'd1f6c60ce95607ea1ef236430d5fdec9',
+    'horizontal-bar': '85855283b7e03010097cb81cde11a91d',
+    image: '15fe506403f8a98575b6df59008ea8f1',
+    'indicator-scorecard': '9d31ba4d773ce32ef350d4A555b673f6e',
+    line: '18ac962264404bcc0039359d184b15f3',
+    list: '7ff373544303121093711347efb8f23c',
+    pareto: '53e0a2b49e3ff92ba54ea7ea6f0d0583',
+    pie: '96abe7e38d8790718022c5630a92176c',
+    'pivot-table': '06f6aacbd1818110f877d87436272684',
+    'rich-text': '2d56f06d55f46bbd4e79b5e624beb940',
+    scatter: 'e3aade757ef3da131076d005cada40d5',
+    'semi-donut': '3809c6583b8dd540a0bf735ed493bae2',
+    'single-score': 'd24d53f60350de7a652caf3188a46ed2',
+    spline: '0f1e76928c4814e1430774fb864003f0',
+    step: '7fa5f7264941fabfb1542985da30e0b8',
+    'vertical-bar': '23051643b7e03010097cb81cde11a910',
+}
+
+/**
+ * Mapping of sys_ids to human-readable component names (kebab-case)
+ */
+const COMPONENT_SYSID_TO_NAME: Record<string, string> = Object.fromEntries(
+    Object.entries(COMPONENT_NAME_TO_SYSID).map(([name, sysid]) => [sysid, name])
+)
+
+/**
+ * Resolves a component value to its sys_id.
+ * If the value is already a sys_id (32-char hex), returns it as-is.
+ * If the value is a component name (case-insensitive), returns the corresponding sys_id.
+ * Otherwise, returns the value unchanged.
+ */
+export function resolveComponentToSysId(component: string): string {
+    // If it's already a sys_id (32 hex chars), return as-is
+    if (/^[0-9a-f]{32}$/i.test(component)) {
+        return component
+    }
+    // Normalize to lowercase for case-insensitive lookup
+    const normalized = component.toLowerCase()
+    // If it's a known component name, resolve to sys_id
+    if (COMPONENT_NAME_TO_SYSID[normalized]) {
+        return COMPONENT_NAME_TO_SYSID[normalized]
+    }
+    // Otherwise return as-is (could be a custom component reference)
+    return component
+}
+
+/**
+ * Resolves a sys_id to its human-readable component name (kebab-case).
+ * If the sys_id has a known name, returns the name.
+ * Otherwise, returns the sys_id unchanged.
+ */
+export function resolveComponentToName(sysid: string): string {
+    return COMPONENT_SYSID_TO_NAME[sysid] || sysid
+}