@synergy-design-system/metadata 1.0.0 → 3.0.1

package/data/layers/interface/component/component:syn-combobox.md

@@ -0,0 +1,388 @@
+# syn-combobox
+
+## Summary
+
+A combobox component that combines the functionality of a text input with a dropdown listbox,
+allowing users to either select from predefined options or enter custom values (when not restricted).
+
+## Documentation
+
+- [Component Documentation](https://synergy-design-system.github.io/?path=/docs/components-syn-combobox--docs)
+- [Figma Design](https://www.figma.com/file/bZFqk9urD3NlghGUKrkKCR/Synergy-Digital-Design-System?type=design&node-id=42207-352063)
+
+## Class Information
+
+- **Tag Name:** `syn-combobox`
+- **Import Example:** `import SynCombobox from '@synergy-design-system/components/components/combobox/combobox.js';`
+
+## Usage Information
+
+- **Status:** stable
+- **Since:** unknown
+
+## Available Slots
+
+- `(default)`: The listbox options. Must be `<syn-option>` elements. You can use `<syn-optgroup>`'s to group items visually.
+- `label`: The combobox's label. Alternatively, you can use the `label` attribute.
+- `prefix`: Used to prepend a presentational icon or similar element to the combobox.
+- `suffix`: Used to append a presentational icon or similar element to the combobox.
+- `clear-icon`: An icon to use in lieu of the default clear icon.
+- `expand-icon`: The icon to show when the control is expanded and collapsed. Rotates on open and close.
+- `help-text`: Text that describes how to use the combobox. Alternatively, you can use the `help-text` attribute.
+
+## Available Properties
+
+### clearable
+
+attribute: `clearable`
+reflects: no
+type: `boolean`
+default: `false`
+
+Adds a clear button when the combobox is not empty.
+
+### defaultValue
+
+attribute: -
+reflects: -
+type: `string | number | Array<string | number>`
+default: `''`
+
+The default value of the form control. Primarily used for resetting the form control.
+
+### delimiter
+
+attribute: `delimiter`
+reflects: no
+type: `string`
+default: `' '`
+
+The delimiter to use when setting the value when `multiple` is enabled. The default is a space ' ', but you can set it to a comma or other character(s).
+
+### disabled
+
+attribute: `disabled`
+reflects: yes
+type: `boolean`
+default: `false`
+
+Disables the combobox control.
+
+### filter
+
+attribute: `filter`
+reflects: no
+type: `(option: SynOption, queryString: string) => boolean`
+default: none
+
+A function used to filter options in the combobox component. The default filter method is a case- and diacritic-insensitive string comparison.
+
+### form
+
+attribute: `form`
+reflects: yes
+type: `string`
+default: `''`
+
+By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you to place the form control outside of a form and associate it with the form that has this `id`. The form must be in the same document or shadow root for this to work.
+
+### getOption
+
+attribute: `getOption`
+reflects: no
+type: `OptionRenderer`
+default: `defaultOptionRenderer`
+
+A function that customizes the rendered option. The first argument is the option, the second is the query string, which is typed into the combobox. The function should return either a Lit TemplateResult or a string containing trusted HTML to render in the shown list of filtered options. If the query string should be highlighted use the `highlightOptionRenderer` function.
+
+### getTag
+
+attribute: `getTag`
+reflects: no
+type: `(option: SynOption, index: number) => TemplateResult | string | HTMLElement`
+default: none
+
+A function that customizes the tags to be rendered when `multiple` is true. The first argument is the option, the second is the current tag's index. The function should return either a Lit TemplateResult or a string containing trusted HTML of the symbol to render at the specified value.
+
+### helpText
+
+attribute: `help-text`
+reflects: no
+type: `string`
+default: `''`
+
+The combobox's help text. If you need to display HTML, use the `help-text` slot instead.
+
+### label
+
+attribute: `label`
+reflects: no
+type: `string`
+default: `''`
+
+The combobox's label. If you need to display HTML, use the `label` slot instead.
+
+### maxlength
+
+attribute: `maxlength`
+reflects: no
+type: `number`
+default: none
+
+The maximum length of input that will be considered valid.
+
+### maxOptionsVisible
+
+attribute: `max-options-visible`
+reflects: no
+type: `number`
+default: `3`
+
+The maximum number of selected options to show when `multiple` is true. After the maximum, "+n" will be shown to indicate the number of additional items that are selected. Set to 0 to remove the limit.
+
+### multiple
+
+attribute: `multiple`
+reflects: yes
+type: `boolean`
+default: `false`
+
+Allows more than one option to be selected. If `multiple` is set, the combobox will always be `restricted` to the available options
+
+### name
+
+attribute: `name`
+reflects: no
+type: `string`
+default: `''`
+
+The name of the combobox, submitted as a name/value pair with form data.
+
+### open
+
+attribute: `open`
+reflects: yes
+type: `boolean`
+default: `false`
+
+Indicates whether or not the combobox is open. You can toggle this attribute to show and hide the listbox, or you can use the `show()` and `hide()` methods and this attribute will reflect the combobox's open state.
+
+### placeholder
+
+attribute: `placeholder`
+reflects: no
+type: `string`
+default: `''`
+
+Placeholder text to show as a hint when the combobox is empty.
+
+### placement
+
+attribute: `placement`
+reflects: yes
+type: `'top' | 'bottom'`
+default: `'bottom'`
+
+The preferred placement of the combobox's menu. Note that the actual placement may vary as needed to keep the listbox inside of the viewport.
+
+### readonly
+
+attribute: `readonly`
+reflects: yes
+type: `boolean`
+default: `false`
+
+Sets the combobox to a readonly state.
+
+### required
+
+attribute: `required`
+reflects: yes
+type: `boolean`
+default: `false`
+
+The combobox's required attribute.
+
+### restricted
+
+attribute: `restricted`
+reflects: yes
+type: `boolean`
+default: `false`
+
+When set to `true`, restricts the combobox to only allow selection from the available options. Users will not be able to enter custom values that are not present in the list. This will always be true, if `multiple` is active.
+
+### size
+
+attribute: `size`
+reflects: yes
+type: `'small' | 'medium' | 'large'`
+default: `'medium'`
+
+The combobox's size.
+
+### value
+
+attribute: `value`
+reflects: no
+type: `undefined`
+default: none
+
+The current value of the combobox, submitted as a name/value pair with form data. When `multiple` is enabled, the value attribute will be a list of values separated by the delimiter, based on the options selected, and the value property will be an array. **For this reason, values must not contain the delimiter character.**
+
+## Available Methods
+
+### blur()
+
+parameters: -
+returns: `void`
+
+Removes focus from the control.
+
+### checkValidity()
+
+parameters: -
+returns: `void`
+
+Checks for validity but does not show a validation message.
+Returns `true` when valid and `false` when invalid.
+
+### focus()
+
+parameters: `options: FocusOptions`
+returns: `void`
+
+Sets focus on the control.
+
+### getForm()
+
+parameters: -
+returns: `void`
+
+Gets the associated form, if one exists.
+
+### hide()
+
+parameters: -
+returns: `void`
+
+Hides the listbox.
+
+### reportValidity()
+
+parameters: -
+returns: `void`
+
+Checks for validity and shows the browser's validation message if the control is invalid.
+
+### setCustomValidity()
+
+parameters: `message: string`
+returns: `void`
+
+Sets a custom validation message. Pass an empty string to restore validity.
+
+### show()
+
+parameters: -
+returns: `void`
+
+Shows the listbox. If it is not possible to open the listbox, because there are no
+appropriate filtered options, a syn-error is emitted and the listbox stays closed.
+
+## Available CSS Parts
+
+- `clear-button`: The clear button.
+- `combobox`: The container that wraps the prefix, combobox, clear icon, and expand button.
+- `display-input`: The element that displays the selected option's label, an `<input>` element.
+- `expand-icon`: The container that wraps the expand icon.
+- `filtered-listbox`: The container that wraps the filtered options.
+- `form-control`: The form control that wraps the label, combobox, and help text.
+- `form-control-help-text`: The help text's wrapper.
+- `form-control-input`: The combobox's wrapper.
+- `form-control-label`: The label's wrapper.
+- `listbox`: The listbox container where the options are slotted and the filtered options list exists.
+- `no-results`: The container that wraps the "no results" message.
+- `popup`: The popup's exported `popup` part. Use this to target the tooltip's popup container.
+- `prefix`: The container that wraps the prefix slot.
+- `suffix`: The container that wraps the suffix slot.
+- `tag`: The individual tags that represent each selected option in `multiple`.
+- `tag__base`: The tag's base part.
+- `tag__content`: The tag's content part.
+- `tag__remove-button`: The tag's remove button.
+- `tag__remove-button__base`: The tag's remove button base part.
+- `tags`: The container that houses option tags when `multiple` is used.
+
+## Available Events
+
+### syn-after-hide
+
+type: `SynAfterHideEvent`
+
+Emitted after the combobox's menu closes and all animations are complete.
+
+### syn-after-show
+
+type: `SynAfterShowEvent`
+
+Emitted after the combobox's menu opens and all animations are complete.
+
+### syn-blur
+
+type: `SynBlurEvent`
+
+Emitted when the control loses focus.
+
+### syn-change
+
+type: `SynChangeEvent`
+
+Emitted when the control's value changes.
+
+### syn-clear
+
+type: `SynClearEvent`
+
+Emitted when the control's value is cleared.
+
+### syn-error
+
+type: `SynErrorEvent`
+
+Emitted when the combobox menu fails to open.
+
+### syn-focus
+
+type: `SynFocusEvent`
+
+Emitted when the control gains focus.
+
+### syn-hide
+
+type: `SynHideEvent`
+
+Emitted when the combobox's menu closes.
+
+### syn-input
+
+type: `SynInputEvent`
+
+Emitted when the control receives input.
+
+### syn-invalid
+
+type: `SynInvalidEvent`
+
+Emitted when the form control has been checked for validity and its constraints aren't satisfied.
+
+### syn-show
+
+type: `SynShowEvent`
+
+Emitted when the combobox's menu opens.
+
+## Dependencies
+
+- `syn-icon`
+- `syn-popup`
+- `syn-tag`

package/data/layers/interface/component/component:syn-details.json

@@ -0,0 +1,202 @@
+{
+  "attributes": [
+    {
+      "default": "false",
+      "description": "Draws the details as contained element.",
+      "fieldName": "contained",
+      "name": "contained",
+      "reflects": true,
+      "type": "boolean"
+    },
+    {
+      "default": "false",
+      "description": "Disables the details so it can't be toggled.",
+      "fieldName": "disabled",
+      "name": "disabled",
+      "reflects": true,
+      "type": "boolean"
+    },
+    {
+      "default": "false",
+      "description": "Indicates whether or not the details is open. You can toggle this attribute to show and hide the details, or you\ncan use the `show()` and `hide()` methods and this attribute will reflect the details' open state.",
+      "fieldName": "open",
+      "name": "open",
+      "reflects": true,
+      "type": "boolean"
+    },
+    {
+      "default": "'medium'",
+      "description": "The details's size.",
+      "fieldName": "size",
+      "name": "size",
+      "reflects": true,
+      "type": "'small' | 'medium' | 'large'"
+    },
+    {
+      "description": "The summary to show in the header. If you need to display HTML, use the `summary` slot instead.",
+      "fieldName": "summary",
+      "name": "summary",
+      "reflects": false,
+      "type": "string"
+    }
+  ],
+  "cssParts": [
+    {
+      "description": "The component's base wrapper.",
+      "name": "base"
+    },
+    {
+      "description": "The container that wraps the details content.",
+      "name": "body"
+    },
+    {
+      "description": "The details content.",
+      "name": "content"
+    },
+    {
+      "description": "The header that wraps both the summary and the expand/collapse icon.",
+      "name": "header"
+    },
+    {
+      "description": "The container that wraps the summary.",
+      "name": "summary"
+    },
+    {
+      "description": "The container that wraps the expand/collapse icons.",
+      "name": "summary-icon"
+    }
+  ],
+  "dependencies": [
+    "syn-icon"
+  ],
+  "documentation": "https://synergy-design-system.github.io/?path=/docs/components-syn-details--docs",
+  "events": [
+    {
+      "description": "Emitted after the details closes and all animations are complete.",
+      "name": "syn-after-hide",
+      "type": "SynAfterHideEvent"
+    },
+    {
+      "description": "Emitted after the details opens and all animations are complete.",
+      "name": "syn-after-show",
+      "type": "SynAfterShowEvent"
+    },
+    {
+      "description": "Emitted when the details closes.",
+      "name": "syn-hide",
+      "type": "SynHideEvent"
+    },
+    {
+      "description": "Emitted when the details opens.",
+      "name": "syn-show",
+      "type": "SynShowEvent"
+    }
+  ],
+  "figmaComponentId": "41227-232486",
+  "methods": [
+    {
+      "description": "",
+      "name": "handleOpenChange",
+      "parameters": []
+    },
+    {
+      "description": "Hides the details",
+      "name": "hide",
+      "parameters": []
+    },
+    {
+      "description": "Shows the details.",
+      "name": "show",
+      "parameters": []
+    }
+  ],
+  "properties": [
+    {
+      "access": "public",
+      "description": "",
+      "name": "body",
+      "type": "HTMLElement"
+    },
+    {
+      "access": "public",
+      "default": "false",
+      "description": "Draws the details as contained element.",
+      "name": "contained",
+      "type": "boolean"
+    },
+    {
+      "access": "public",
+      "description": "",
+      "name": "details",
+      "type": "HTMLDetailsElement"
+    },
+    {
+      "access": "public",
+      "description": "",
+      "name": "detailsObserver",
+      "type": "MutationObserver"
+    },
+    {
+      "access": "public",
+      "default": "false",
+      "description": "Disables the details so it can't be toggled.",
+      "name": "disabled",
+      "type": "boolean"
+    },
+    {
+      "access": "public",
+      "description": "",
+      "name": "expandIconSlot",
+      "type": "HTMLSlotElement"
+    },
+    {
+      "access": "public",
+      "description": "",
+      "name": "header",
+      "type": "HTMLElement"
+    },
+    {
+      "access": "public",
+      "default": "false",
+      "description": "Indicates whether or not the details is open. You can toggle this attribute to show and hide the details, or you\ncan use the `show()` and `hide()` methods and this attribute will reflect the details' open state.",
+      "name": "open",
+      "type": "boolean"
+    },
+    {
+      "access": "public",
+      "default": "'medium'",
+      "description": "The details's size.",
+      "name": "size",
+      "type": "'small' | 'medium' | 'large'"
+    },
+    {
+      "access": "public",
+      "description": "The summary to show in the header. If you need to display HTML, use the `summary` slot instead.",
+      "name": "summary",
+      "type": "string"
+    }
+  ],
+  "since": "2.0",
+  "slots": [
+    {
+      "description": "The details' main content.",
+      "name": ""
+    },
+    {
+      "description": "The details' summary. Alternatively, you can use the `summary` attribute.",
+      "name": "summary"
+    },
+    {
+      "description": "Optional expand icon to use instead of the default. Works best with `<syn-icon>`.",
+      "name": "expand-icon"
+    },
+    {
+      "description": "Optional collapse icon to use instead of the default. Works best with `<syn-icon>`.",
+      "name": "collapse-icon"
+    }
+  ],
+  "sourceModulePath": "components/details/details.js",
+  "status": "stable",
+  "summary": "Details show a brief summary and expand to show additional content.",
+  "tagName": "syn-details"
+}

package/data/layers/interface/component/component:syn-details.md

@@ -0,0 +1,129 @@
+# syn-details
+
+## Summary
+
+Details show a brief summary and expand to show additional content.
+
+## Documentation
+
+- [Component Documentation](https://synergy-design-system.github.io/?path=/docs/components-syn-details--docs)
+- [Figma Design](https://www.figma.com/file/bZFqk9urD3NlghGUKrkKCR/Synergy-Digital-Design-System?type=design&node-id=41227-232486)
+
+## Class Information
+
+- **Tag Name:** `syn-details`
+- **Import Example:** `import SynDetails from '@synergy-design-system/components/components/details/details.js';`
+
+## Usage Information
+
+- **Status:** stable
+- **Since:** 2.0
+
+## Available Slots
+
+- `(default)`: The details' main content.
+- `summary`: The details' summary. Alternatively, you can use the `summary` attribute.
+- `expand-icon`: Optional expand icon to use instead of the default. Works best with `<syn-icon>`.
+- `collapse-icon`: Optional collapse icon to use instead of the default. Works best with `<syn-icon>`.
+
+## Available Properties
+
+### contained
+
+attribute: `contained`
+reflects: yes
+type: `boolean`
+default: `false`
+
+Draws the details as contained element.
+
+### disabled
+
+attribute: `disabled`
+reflects: yes
+type: `boolean`
+default: `false`
+
+Disables the details so it can't be toggled.
+
+### open
+
+attribute: `open`
+reflects: yes
+type: `boolean`
+default: `false`
+
+Indicates whether or not the details is open. You can toggle this attribute to show and hide the details, or you can use the `show()` and `hide()` methods and this attribute will reflect the details' open state.
+
+### size
+
+attribute: `size`
+reflects: yes
+type: `'small' | 'medium' | 'large'`
+default: `'medium'`
+
+The details's size.
+
+### summary
+
+attribute: `summary`
+reflects: no
+type: `string`
+default: none
+
+The summary to show in the header. If you need to display HTML, use the `summary` slot instead.
+
+## Available Methods
+
+### hide()
+
+parameters: -
+returns: `void`
+
+Hides the details
+
+### show()
+
+parameters: -
+returns: `void`
+
+Shows the details.
+
+## Available CSS Parts
+
+- `base`: The component's base wrapper.
+- `body`: The container that wraps the details content.
+- `content`: The details content.
+- `header`: The header that wraps both the summary and the expand/collapse icon.
+- `summary`: The container that wraps the summary.
+- `summary-icon`: The container that wraps the expand/collapse icons.
+
+## Available Events
+
+### syn-after-hide
+
+type: `SynAfterHideEvent`
+
+Emitted after the details closes and all animations are complete.
+
+### syn-after-show
+
+type: `SynAfterShowEvent`
+
+Emitted after the details opens and all animations are complete.
+
+### syn-hide
+
+type: `SynHideEvent`
+
+Emitted when the details closes.
+
+### syn-show
+
+type: `SynShowEvent`
+
+Emitted when the details opens.
+
+## Dependencies
+
+- `syn-icon`