@vonage/vivid-react 2.10.47 → 2.10.58

package/scripts/generateWrappers/templates/js/react-component.tmpl

@@ -0,0 +1,30 @@
+<% banner %>
+/*
+Code in this file were generated using following JSON:
+<% descriptor-json %>
+*/
+import PropTypes from 'prop-types'
+import wrapper from '@vonage/vivid-react-wrapper'
+<% imports %>
+<% react-import %>
+
+<% jsdoc.class %>
+const <% component-class-name %> = wrapper('<% tag %>',  {
+    events: [<% events %>],
+    attributes: [<% attributes %>],
+    properties: [<% properties %>]
+});
+
+<% component-class-name %>.propTypes = {
+<% prop-types %>
+}
+
+<% component-class-name %>.defaultProps = {
+<% default-props %>
+}
+
+<% component-class-name %>.displayName = '<% component-class-name %>'
+
+<% compound-components %>
+
+export default <% component-class-name %>

package/scripts/generateWrappers/templates/js/stories.tmpl

@@ -0,0 +1,18 @@
+import React from 'react'
+import <% component-class-name %> from '../../../dist/<% component-class-name %>'
+
+export const Default = () => <<% component-class-name %> />
+export default {
+  title: 'V2/<% component-class-name %>',
+  argTypes: {
+      //
+      // Example values
+      // numberValue: { control: 'number', defaultValue: 123 },
+      // booleanValue: { control: 'boolean', defaultValue: true },
+      // objectValue: { control: 'object', defaultValue: {} },
+      // stringValue: { control: 'string', defaultValue: 'string' },
+      // colorValue: { control: 'color' },
+      // dateValue: { control: 'date' }
+      //
+    }
+}

package/scripts/generateWrappers/templates/templates.js

@@ -0,0 +1,39 @@
+/*
+* Purpose: Support code-generation activities with templates
+*/
+const { readFileSync } = require('fs')
+
+const TemplateToken = {
+  BANNER: '<% banner %>',
+  IMPORTS: '<% imports %>',
+  EXPORTS: '<% exports %>',
+  TAG: '<% tag %>',
+  ELEMENT_TYPES: '<% element-types %>',
+  COMPONENT_CLASS_NAME: '<% component-class-name %>',
+  COMPONENT_NAME: '<% component-name %>',
+  TAG_PREFIX: '<% tag-prefix %>',
+  PROP_TYPES: '<% prop-types %>',
+  PROPS: '<% props %>',
+  DEFAULT_PROPS: '<% default-props %>',
+  PROPERTIES: '<% properties %>',
+  ATTRIBUTES: '<% attributes %>',
+  EVENTS: '<% events %>',
+  CLASS_JSDOC: '<% jsdoc.class %>',
+  TAG_DESCRIPTOR_JSON: '<% descriptor-json %>',
+  COMPOUND_COMPONENTS: '<% compound-components %>',
+  REACT_IMPORT: '<% react-import %>'
+}
+
+const GENERATED_CODE_BANNER = `/*
+* DO NOT EDIT THIS FILE. IT IS GENERATED
+*/`
+const templatesFolder = `${__dirname}`
+const getTemplate = (template, language) =>
+  readFileSync(`${templatesFolder}/${language}/${template}.tmpl`, { encoding: 'utf8' })
+    .replace(TemplateToken.BANNER, GENERATED_CODE_BANNER)
+
+module.exports = {
+  getTemplate,
+  TemplateToken,
+  GENERATED_CODE_BANNER
+}

package/scripts/generateWrappers/templates/ts/element-type.tmpl

@@ -0,0 +1,3 @@
+        "<% tag %>": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & Partial<{
+<% attributes %>
+        }>;

package/scripts/generateWrappers/templates/ts/index.tmpl

@@ -0,0 +1,2 @@
+<% banner %>
+<% exports %>

package/scripts/generateWrappers/templates/ts/react-component-v3.tmpl

@@ -0,0 +1,32 @@
+<% banner %>
+/*
+Code in this file were generated using following JSON:
+<% descriptor-json %>
+*/
+import React, { ReactNode, SyntheticEvent, ForwardRefExoticComponent } from 'react'
+import wrapper from '@vonage/vivid-react-wrapper'
+import { register<% component-name %> } from '@vonage/vivid'
+
+register<% component-name %>('<% tag-prefix %>')
+
+const WrappedComponent = wrapper(`<% tag %>`,  {
+    events: [<% events %>],
+    attributes: [<% attributes %>],
+    properties: [<% properties %>]
+}) as ForwardRefExoticComponent<any>;
+
+<% jsdoc.class %>
+const <% component-class-name %> = (props:
+{
+  children?: ReactNode,
+  slot?: string,
+  id?: string,
+  style?: React.CSSProperties,
+  ref?: ((instance: HTMLDivElement | null) => void) | React.RefObject<HTMLDivElement> | null | undefined,
+<% props %>
+}
+): JSX.Element => <WrappedComponent {...props}>{props.children}</WrappedComponent>
+
+<% component-class-name %>.displayName = '<% component-class-name %>'
+
+export default <% component-class-name %>

package/scripts/generateWrappers/templates/ts/react-component.tmpl

@@ -0,0 +1,28 @@
+<% banner %>
+/*
+Code in this file were generated using following JSON:
+<% descriptor-json %>
+*/
+import React, { ReactNode, SyntheticEvent, ForwardRefExoticComponent } from 'react'
+import wrapper from '@vonage/vivid-react-wrapper'
+<% imports %>
+
+const WrappedComponent = wrapper('<% tag %>',  {
+    events: [<% events %>],
+    attributes: [<% attributes %>],
+    properties: [<% properties %>]
+}) as ForwardRefExoticComponent<any>;
+
+<% jsdoc.class %>
+const <% component-class-name %> = (props:
+{
+  children?: ReactNode,
+  slot?: string,
+  id?: string,
+  style?: React.CSSProperties,
+  ref?: ((instance: HTMLDivElement | null) => void) | React.RefObject<HTMLDivElement> | null | undefined,
+<% props %>
+}
+): JSX.Element => <WrappedComponent {...props}>{props.children}</WrappedComponent>
+
+export default <% component-class-name %>

package/scripts/generateWrappers/templates/ts/types.tmpl

@@ -0,0 +1,8 @@
+<% banner %>
+declare module '@vonage/vivid-react-wrapper';
+declare module '@vonage/vivid-react';
+declare namespace JSX {
+    interface IntrinsicElements {
+<% element-types %>
+    }
+}

package/scripts/generateWrappers/utils.js

@@ -0,0 +1,197 @@
+const { join, parse } = require('path')
+const { flowRight, map, replace, reverse, startCase, uniqBy } = require('lodash/fp')
+const { access, F_OK, readFileSync, existsSync, rmSync } = require('fs')
+const mkdirp = require('mkdirp')
+const { spawnSync } = require('child_process')
+const { WCAConfig, VividRepo, FileName, OutputLanguage, ComponentsBindablePropertiesMap, ComponentsReadOnlyPropertiesMap, ComponentsExtraPropertiesMap } = require('./consts')
+const { copySync } = require('fs-extra')
+
+const renderPropertyJsDoc = tag => property => `* @param ${property.type ? `{${property.type}}` : ''} ${property.name} ${property.description ? `- ${property.description}` : ''} ${property.attribute ? `attribute: <${getComponentName(tag)} ${property.attribute} />` : ''}`
+const renderTagPropertiesJsDoc = tag => getProperties(tag).map(renderPropertyJsDoc(tag)).join('\n')
+const renderJsDoc = tag => `/** ${tag.description || ''} \n${renderTagPropertiesJsDoc(tag)}\n*/`
+const stripQuotes = input => input.replace(/'/g, '')
+const unique = stringArray => Array.from(new Set(stringArray))
+const toJsonObjectsList = collection => (collection || []).map(JSON.stringify).join(',')
+const toCommaSeparatedList = collection => (collection || []).map(x => `'${stripQuotes(x.name)}'`).join(',')
+const capitalize = input => input.replace(/(^|\s)[a-z]/g, s => s.toUpperCase())
+const deCapitalize = input => input.replace(/(^|\s)[A-Z]/g, s => s.toLowerCase())
+const getComponentName = tag => capitalize(kebab2Camel(tag.name))
+const camel2kebab = input => deCapitalize(input).replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, '-').toLowerCase()
+const kebab2Camel = input => deCapitalize(input.split('-').map(x => capitalize(x)).join(''))
+const snake2Camel = input => deCapitalize(input.split('_').map(x => capitalize(x)).join(''))
+const event2PropName = eventName => `on${capitalize(kebab2Camel(snake2Camel(eventName)))}`
+const event2EventDescriptor = event => typeof event === 'string'
+  ? ({ name: event, propName: event2PropName(event) })
+  : event
+const getUniqueEvents = flowRight(
+  uniqBy('name'),
+  // need to reverse to have custom events first, to allow overwriting of the ones grabbed from JSDocs
+  reverse,
+  map(event2EventDescriptor)
+)
+const isVividPackageName = (packageName) => /@vonage\/vwc-*/.test(packageName)
+const getIndexFileName = language => `index.${language === OutputLanguage.TypeScript ? 'tsx' : language}`
+const getVividPackageName = componentPath => {
+  const { dir } = parse(componentPath)
+  if (dir.indexOf('node_modules') >= 0) {
+    return /(@vonage\/vwc-.*?)\//.exec(componentPath.replace(/\\/g, '/'))[1]
+  }
+  const pathParts = dir.split('\\').join('/').split('/')
+  if (pathParts.length > 0 && pathParts[pathParts.length - 1] === 'src') {
+    pathParts.pop()
+  }
+  const packageJson = filePath(join(FileName.tempFolder, ...pathParts, FileName.packageJson))
+  const pkg = getParsedJson(packageJson)
+  return pkg.name
+}
+const prepareDir = (p, clean = true, verbose = true) => {
+  if (clean && existsSync(p)) {
+    if (verbose) {
+      console.info(`Clearing folder: ${p}`)
+    }
+    rmSync(p, { recursive: true })
+  }
+  mkdirp.sync(p)
+}
+const getProperties = tag => (tag.properties || [])
+  .filter(prop => !(ComponentsReadOnlyPropertiesMap[getComponentName(tag)] || []).includes(prop.name)) // skip readonly properties
+  .filter(prop => /'.*?'/.test(prop.name) ||
+    /^([a-zA-Z_$][a-zA-Z\\d_$]*)$/.test(prop.name)) // only props having valid names
+  .map(prop => {
+    const isBindable = (ComponentsBindablePropertiesMap[getComponentName(tag)] || []).includes(prop.name) ||
+      prop.type?.indexOf('=>') > 0 || // property type is function
+      prop.type?.indexOf('[]') > 0 // property type is array
+    prop.bindable = isBindable
+    return prop
+  }).concat(ComponentsExtraPropertiesMap[getComponentName(tag)] || [])
+
+const isFileExists = (fileName) => new Promise(
+  (resolve, reject) => access(
+    filePath(fileName),
+    F_OK,
+    error => error
+      ? reject(error)
+      : resolve(fileName)
+  ))
+const filePath = (fileName) => join(process.cwd(), fileName)
+
+const readMetaData = () => new Promise(
+  (resolve) => {
+    const vividPackageFolder = join(process.cwd(), 'node_modules/@vonage/vivid')
+    const elementsMetaData = `${vividPackageFolder}/${FileName.customElements}`
+    const apiMetaData = `${vividPackageFolder}/${FileName.vividApi}`
+    const meta = {
+      api: getParsedJson(apiMetaData),
+      elements: getParsedJson(elementsMetaData)
+    }
+    resolve(meta)
+  })
+
+const getParsedJson = (jsonFilePath) => JSON.parse(readFileSync(jsonFilePath, { encoding: 'utf8' }))
+
+const getVividPackageNames = ({ dependencies, devDependencies }) => {
+  const packages = [
+    ...Object.keys(dependencies),
+    ...Object.keys(devDependencies)
+  ]
+  const result = unique(packages).filter(isVividPackageName)
+  console.log(`Vivid packages detected from ${FileName.packageJson}: \n${result.map(x => `  - ${x}`).join('\n')}`)
+  return result
+}
+
+const getCustomElementTagsDefinitionsList = (config = WCAConfig) => (vividPackageNames) => new Promise((resolve) => {
+  const analyzerOutput = filePath(join(config.tempFolder, config.tempFileName))
+  const child = spawnSync(
+    'node',
+    config.nodeArgumentsFactory(vividPackageNames, analyzerOutput),
+    { cwd: process.cwd() }
+  )
+  if (child.status === 0) {
+    const output = getParsedJson(analyzerOutput)
+    const uniqueTags = unique(output.tags.map(x => x.name)).map(x => output.tags.find(y => y.name === x))
+    return resolve(uniqueTags)
+  }
+})
+
+const compileTypescript = (rootDir) => async (outDir) =>
+  spawnSync(
+    'node',
+    [
+      './node_modules/typescript/lib/tsc.js',
+      '--project',
+      filePath('tsconfig.json'),
+      '--rootDir',
+      rootDir,
+      '--outDir',
+      outDir
+    ]
+  )
+
+const copyStaticAssets = (outputDir, assets) => () => {
+  const cp = file => {
+    const source = filePath(file)
+    const dest = filePath(join(outputDir, file))
+    copySync(source, dest)
+    console.info(`Copy static asset ${source} => ${dest}`)
+  }
+  assets.split(',').map(assetFileName => cp(assetFileName))
+}
+
+const getInputArgument = (argumentName, defaultValue = null) => {
+  const argumentObjects = process.argv
+    .filter(argument => argument.indexOf('=') >= 0)
+    .map(argument => ({
+      name: argument.split('=')[0].replace(/--/g, ''),
+      value: argument.split('=')[1]
+    }))
+  const targetArgument = argumentObjects.find(argumentObject => argumentObject.name === argumentName)
+  return targetArgument ? targetArgument.value : defaultValue
+}
+
+const getComponentNameFromPackage = flowRight(
+  replace(/\s/g, ''),
+  startCase,
+  replace('@vonage/', '')
+)
+
+const compoundComponentTemplate = (baseName, compositeName, defaultProps) =>
+  `const ${compositeName} = (props) => createElement(${baseName}, props)
+
+${compositeName}.defaultProps = ${JSON.stringify(defaultProps)}
+
+${baseName}.${compositeName} = ${compositeName}`
+
+const prepareCompoundComponents = (baseName, template, compoundComponentsConfig = {}) => () => Object
+  .entries(compoundComponentsConfig)
+  .map(([compositeName, defaultProps]) => template(baseName, compositeName, defaultProps))
+  .join('\n\n')
+
+module.exports = {
+  toCommaSeparatedList,
+  toJsonObjectsList,
+  compileTypescript,
+  filePath,
+  prepareDir,
+  renderJsDoc,
+  capitalize,
+  kebab2Camel,
+  event2PropName,
+  event2EventDescriptor,
+  getComponentNameFromPackage,
+  getInputArgument,
+  getUniqueEvents,
+  readMetaData,
+  camel2kebab,
+  isFileExists,
+  isVividPackageName,
+  copyStaticAssets,
+  getIndexFileName,
+  getProperties,
+  getComponentName,
+  getParsedJson,
+  getVividPackageName,
+  getVividPackageNames,
+  getCustomElementTagsDefinitionsList,
+  prepareCompoundComponents,
+  compoundComponentTemplate
+}

package/scripts/generateWrappers/utils.test.js

@@ -0,0 +1,71 @@
+import { jest } from '@jest/globals'
+import { getUniqueEvents } from './utils'
+
+const { getVividPackageNames, event2PropName, prepareCompoundComponents } = require('./utils')
+
+it('getVividPackageNames', () => {
+  const packageJson = {
+    dependencies: {
+      '@vonage/vwc-button': '0.1',
+      '@vonage/vwc-icon': '0.2',
+      '@nvm/vwc-badge': '0.2'
+    },
+    devDependencies: {
+      '@vonage/vwc-dropdown': '0.1',
+      '@vonage/component': '0.2'
+    },
+    otherDependencies: {
+      '@vonage/vwc-nav': '0.3'
+    }
+  }
+  const expectedList = [
+    '@vonage/vwc-button',
+    '@vonage/vwc-icon',
+    '@vonage/vwc-dropdown'
+  ]
+  expect(getVividPackageNames(packageJson)).toStrictEqual(expectedList)
+})
+
+it.each([
+  ['digit-added', 'onDigitAdded'],
+  ['userScrubRequest', 'onUserScrubRequest'],
+  ['vvd_scheme_select', 'onVvdSchemeSelect']
+])(`event2PropName should convert "%s" to "%s"`, (input, expected) => {
+  expect(event2PropName(input)).toStrictEqual(expected)
+})
+
+it('compound components', () => {
+  const template = jest.fn()
+  const config = {
+    CTA: {
+      connotation: 'cta',
+      layout: 'filled'
+    },
+    Alert: {
+      connotation: 'alert',
+      layout: 'filled'
+    }
+  }
+
+  prepareCompoundComponents('VwcButton', template, config)()
+
+  expect(template.mock.calls[0]).toEqual([
+    'VwcButton',
+    'CTA',
+    config.CTA
+  ])
+  expect(template.mock.calls[1]).toEqual([
+    'VwcButton',
+    'Alert',
+    config.Alert
+  ])
+})
+
+it('getUniqueEvents', () => {
+  const firstEvent = { name: 'non-unique', propName: 'replaced' }
+  const secondEvent = { name: 'non-unique', propName: 'targetPropName' }
+  const uniqueEvent = { name: 'unique', propName: 'onUnique' }
+  const events = [firstEvent, secondEvent, uniqueEvent]
+
+  expect(getUniqueEvents(events)).toEqual([uniqueEvent, secondEvent])
+})

package/scripts/updateDocs.js

@@ -0,0 +1,42 @@
+const os = require('os')
+const { getComponentNameFromPackage } = require('./generateWrappers/utils')
+const { outputFile, readFile } = require('fs-extra')
+
+const { isVividPackageName } = require('./generateWrappers/utils')
+const { dependencies, devDependencies } = require('../package.json')
+
+const generateSupportedComponents = () => {
+  const allDeps = Object.entries({
+    ...devDependencies,
+    ...dependencies
+  })
+
+  const reducePackagesToVividComponentsList = (acc, [name, version]) => {
+    if (!isVividPackageName(name)) {
+      return acc
+    }
+    const componentName = getComponentNameFromPackage(name)
+    return [...acc, `| ${componentName} | ${name} | ${version} |`]
+  }
+
+  return allDeps.reduce(
+    reducePackagesToVividComponentsList,
+    [
+      '| Component Name | Package Name | Package Version |',
+      '|----------------|--------------|-----------------|'
+    ]
+  )
+}
+
+const updateSupportedComponents = async (readmePath) => {
+  const packageList = generateSupportedComponents()
+  const readme = await readFile(readmePath, { encoding: 'utf8' })
+  await outputFile(
+    readmePath,
+    // this finds a table, might be a problem if we have more than one ;)
+    // need the extra empty string to have a new line before the next section
+    readme.replace(/((\|[ -][^|\r\n]*)+\|(\r?\n|\r)?)+/gm, [...packageList, ''].join(os.EOL))
+  )
+}
+
+updateSupportedComponents('README.md')

package/scripts/updateVividPackages.js

@@ -0,0 +1,81 @@
+const ora = require('ora')
+const { EOL } = require('os')
+const { spawn } = require('child_process')
+const { dependencies } = require('../package.json')
+
+const spinner = ora()
+
+const spawnPromise = (...args) => new Promise((resolve, reject) => {
+  const cmd = spawn(...args)
+  const stdout = []
+  const stderr = []
+  cmd.stdout.on('data', (data) => stdout.push(data))
+  cmd.stderr.on('data', (data) => stderr.push(data))
+  cmd.on('close', (status) => status ? reject(stderr.join('')) : resolve(stdout.join('')))
+  cmd.on('error', () => reject(stderr.join('')))
+})
+
+// TODO: find a better way to load complete search results when searching NPM
+// naive way to force paging when doing NPM search
+// NPM limits the number of packages it returns and drops some versions and packages all together
+const forcePaging = (pattern = '') =>
+  'abcdefghijklmnopqrstuvwxyz'.split('').map((letter) => `${pattern}-${letter}`)
+
+const ignoredPackages = [
+  '@vonage/vwc-angular-forms',
+  '@vonage/vwc-angular-dialog',
+  '@vonage/vwc-toggle-buttons-group',
+  '@vonage/vwc-relative-time'
+]
+
+const defaultPatterns = [
+  'vonage/vvd-context',
+  'vonage/vvd-core',
+  'vonage/vvd-fonts',
+  ...forcePaging('vonage/vwc')
+]
+
+const removeIgnoredPackages = ({ name }) => !ignoredPackages.includes(name)
+
+const keepOnlyChangedPackages = ({ name, version }) => dependencies[name] !== `^${version}`
+
+const getPackages = async (patterns = defaultPatterns) => {
+  const packages = []
+  spinner.start('')
+  for (const pattern of patterns) {
+    spinner.text = `Searching for Vivid packages to update. [found: ${packages.length}]`
+    try {
+      const stdout = await spawnPromise('npm', ['search', '--json', '--no-description', pattern], { encoding: 'utf8' })
+      packages.push(...JSON.parse(stdout).filter(removeIgnoredPackages).filter(keepOnlyChangedPackages))
+    } catch {
+    }
+  }
+  spinner.clear()
+  return packages
+}
+
+const updatePackageJson = async () => {
+  const packages = await getPackages()
+  if (!packages.length) {
+    spinner.info('Nothing to update. All packages already in latest versions.')
+    return
+  }
+  let updated = 0
+  spinner.succeed(`Found ${packages.length} packages needing update.`)
+  spinner.start()
+  for (const { name, version } of packages) {
+    const versionedPackage = `${name}@^${version}`
+    spinner.text = `Updating '${name}@${dependencies[name]}' to '^${version}'. [updated: ${updated}/${packages.length}]`
+    try {
+      await spawnPromise('yarn', ['add', versionedPackage], { encoding: 'utf8' })
+      updated++
+    } catch (errorMessage) {
+      spinner.fail()
+      spinner.fail(errorMessage.trim(EOL))
+      spinner.start()
+    }
+  }
+  spinner.info(`Updated ${updated} of ${packages.length}`)
+}
+
+updatePackageJson()

package/src/dataGrid/index.js

@@ -0,0 +1,15 @@
+/* global HTMLElement */
+import { createRoot } from 'react-dom/client'
+
+/**
+ * Renders the cell contents using React 18.x api
+ *
+ * @param {ReactNode} children - renderer contents
+ * @param {Container & { rootRenderer?: Root }} container - HTMLElement root container
+ */
+export const cellRendererFactory = (children, container) => {
+    const root = container?.rootRenderer ?? createRoot(container)
+
+    root.render(children)
+    container.rootRenderer = root
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export * from './initialization/initVivid'
+export * from './patches'
+export * from './dataGrid'

package/src/initialization/initVivid.js

@@ -0,0 +1,56 @@
+/* global HTMLElement */
+import context from '@vonage/vvd-context'
+import { init } from '@vonage/vvd-fonts'
+
+import coreStyles from './../generated/style.core.all'
+import darkThemeStyles from './../generated/style.theme.dark'
+import lightThemeStyles from './../generated/style.theme.light'
+import fontSpeziaStyles from './../generated/style.font.spezia'
+import vividVersion from './../generated/vivid.version'
+
+const vividDataAttributePrefix = 'data-vivid'
+
+const appendStyleElement = (document = window.document) => (styleDescriptor) => {
+  const attributeName = `${vividDataAttributePrefix}-id`
+  if (document.querySelectorAll(`[${attributeName}="${styleDescriptor.id}"]`).length > 0) {
+    return
+  }
+  const styleElement = document.createElement('style')
+  styleElement.setAttribute('type', 'text/css')
+  styleElement.setAttribute(attributeName, styleDescriptor.id)
+  styleElement.innerHTML = styleDescriptor.css
+  document.head.append(styleElement)
+}
+
+/**
+ * mounts Vivid context (styles) & Fonts into the target scope / document
+ * - target scope may by any `HTMLElement` or `Document` or `DocumentFragment` (including `ShadowRoot`)
+ * - default target (when not specified) is the document visible in the current scope
+ * - the API is idempotent, the style/s will be mounted only once, even if API called multiple times
+ *
+ * @param {Document | DocumentFragment | HTMLElement} target - target document/shadow root/element to mount the CSS into
+ * @param {Function} callback - callback function to be invoked once init is done
+ * @param {Object} options - options config how to init vivid. `theme` - dark | light, `font` - proprietary | oss
+ *
+ * @throws {Error} error - if the provided target argument is `null` or not a Node of type `Document` / `DocumentFragment` / `HTMLElement`
+ */
+export const initVivid = (target, callback, options) => {
+  if (target instanceof HTMLElement) {
+    target.classList.add('vivid-scope') // vivid 2.x
+    target.setAttribute(`${vividDataAttributePrefix}-v2`, vividVersion.v2)
+
+    target.classList.add('vvd-root') // vivid 3.x
+    target.setAttribute(`${vividDataAttributePrefix}-v3`, vividVersion.v3)
+    target = undefined
+  }
+  const appendStyle = appendStyleElement()
+  appendStyle(coreStyles)
+  appendStyle(options.theme === 'light' ? lightThemeStyles : darkThemeStyles)
+  if (options.font === 'proprietary') {
+    appendStyle(fontSpeziaStyles)
+  }
+  return Promise.all([
+    init(),
+    context.mount(target)
+  ]).then(callback)
+}

package/src/patches/VwcCard/index.js

@@ -0,0 +1,2 @@
+export * from './vwcCardWithMenu'
+export * from './vwcCardHeadingCrop'

package/src/patches/VwcCard/vwcCardHeadingCrop.js

@@ -0,0 +1,28 @@
+import { vwcTooltipEllipsisDecorator } from "../vwcTooltip"
+
+/**
+ * Patches provided `VwcCard` (styles) to crop long heading text and
+ * shows browser tooltip when actually cropped
+ *
+ * @param {HTMLElement} element - target `VwcCard` element to apply the `heading` cropping logic to
+ * @example <VwcCard ref={vwcCardHeadingCropDecorator(text)} heading={text} />
+ */
+export const vwcCardHeadingCropDecorator = text => element =>
+    setTimeout(() => {
+        const cardContentElement = element?.shadowRoot.querySelector(
+            '.vwc-card-content'
+        )
+        const titleElement = element?.shadowRoot.querySelector(
+            '.vwc-card-title'
+        )
+        vwcTooltipEllipsisDecorator(text)(titleElement)
+        if (cardContentElement?.clientWidth < titleElement?.clientWidth) {
+            const computedCardContentStyle = window.getComputedStyle(cardContentElement, null)
+            titleElement.setAttribute('title', text)
+            titleElement.style.width = computedCardContentStyle.getPropertyValue('width')
+            titleElement.style.overflow = 'hidden'
+            titleElement.style.display = 'block'
+            titleElement.style['white-space'] = 'nowrap'
+            titleElement.style['text-overflow'] = 'ellipsis'
+        }
+    }, 0)