feat: support for Description List UIs

part of #8058

Author: starpit

packages/core/src/index.ts

@@ -239,6 +239,7 @@ export {
   FunctionThatProducesContent
 } from './models/mmr/content-types'
 export { ToolbarText, ToolbarAlert, isSupportedToolbarTextType } from './webapp/views/toolbar-text'
+export { default as DescriptionList, isDescriptionList } from './models/DescriptionList'
 
 // low-level UI
 export { default as doCancel } from './webapp/cancel'

packages/core/src/models/DescriptionList.ts

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2021 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ScalarResource } from './mmr/content-types'
+
+export default interface DescriptionList {
+  apiVersion: 'kui-shell/v1'
+  kind: 'DescriptionList'
+
+  spec: {
+    groups: {
+      /** The term being described */
+      term: string
+
+      /** The description of that term */
+      description: number | boolean | string
+
+      /** Optional help details for the term */
+      termHelp?: {
+        title: string
+        description: number | boolean | string
+      }
+    }[]
+  }
+}
+
+export function isDescriptionList(content: ScalarResource): content is DescriptionList {
+  const dl = content as DescriptionList
+  return (
+    dl.apiVersion === 'kui-shell/v1' &&
+    dl.kind === 'DescriptionList' &&
+    typeof dl.spec === 'object' &&
+    Array.isArray(dl.spec.groups) &&
+    dl.spec.groups.length > 0 &&
+    typeof dl.spec.groups[0].term === 'string' &&
+    typeof dl.spec.groups[0].description !== 'undefined' &&
+    (typeof dl.spec.groups[0].termHelp === 'undefined' ||
+      (typeof dl.spec.groups[0].termHelp === 'object' &&
+        typeof dl.spec.groups[0].termHelp.title === 'string' &&
+        typeof dl.spec.groups[0].termHelp.description !== 'undefined'))
+  )
+}

packages/core/src/models/mmr/content-types.ts

@@ -23,14 +23,15 @@ import { isHTML } from '../../util/types'
 import { ModeOrButton, Button } from './types'
 import { ToolbarText } from '../../webapp/views/toolbar-text'
 import { Editable } from '../editable'
+import DescriptionList, { isDescriptionList } from '../DescriptionList'
 
 /**
  * A `ScalarResource` is Any kind of resource that is directly
  * represented, as opposed to being implicitly represented by a
  * function call.
  *
  */
-export type ScalarResource = string | HTMLElement | Table
+export type ScalarResource = string | HTMLElement | Table | DescriptionList
 export interface ScalarContent<T = ScalarResource> {
   content: T
 }
@@ -57,7 +58,7 @@ export function isScalarContent<T extends MetadataBearing>(entity: ScalarLike<T>
   return (
     isReactProvider(entity) ||
     (content !== undefined &&
-      (typeof content === 'string' || isTable(content) || isHTML(content)))
+      (typeof content === 'string' || isTable(content) || isHTML(content) || isDescriptionList(content)))
   )
 }
 

packages/test/src/api/selectors.ts

@@ -361,3 +361,8 @@ export const EXPANDABLE_OUTPUT_N = (N: number, splitIndex = 1) =>
   `${PROMPT_BLOCK_N_FOR_SPLIT(N, splitIndex)} .kui--expandable-section button`
 export const EXPANDABLE_OUTPUT_LAST = (splitIndex = 1) =>
   `${PROMPT_BLOCK_LAST_FOR_SPLIT(splitIndex)} .kui--expandable-section button`
+
+/** DescriptionList */
+export const DLIST = '.kui--description-list'
+export const DLIST_DESCRIPTION_FOR = (term: string) =>
+  `.kui--description-list-term[data-term=${term}] + .kui--description-list-description`

packages/test/src/api/sidecar-expect.ts

@@ -379,3 +379,36 @@ export function breadcrumbs(breadcrumbs: string[]) {
     return res
   }
 }
+
+/** Expect DescriptionList content in the current tab */
+export const descriptionList = (content: Record<string, number | boolean | string>) => async (res: AppAndCount) => {
+  const container =
+    res.splitIndex !== undefined
+      ? `${Selectors.PROMPT_BLOCK_N_FOR_SPLIT(res.count, res.splitIndex)} .kui--tab-content:not([hidden])`
+      : `${Selectors.PROMPT_BLOCK_N(res.count)} .kui--tab-content:not([hidden])`
+
+  for (const term in content) {
+    let idx = 0
+    await res.app.client.waitUntil(
+      async () => {
+        const expectedDescription = content[term].toString() // the actualDescription will come as a string
+        const actualDescription = await res.app.client
+          .$(`${container} ${Selectors.DLIST_DESCRIPTION_FOR(term)}`)
+          .then(_ => _.getText())
+        if (actualDescription !== expectedDescription) {
+          if (++idx > 5) {
+            console.error(
+              `Still waiting for expectedDescription=${expectedDescription} actualDescription=${actualDescription} `
+            )
+          }
+          return false
+        } else {
+          return true
+        }
+      },
+      { timeout: waitTimeout }
+    )
+  }
+
+  return res
+}

plugins/plugin-client-common/src/components/Content/KuiContent.tsx

@@ -32,6 +32,7 @@ import {
   isFunctionContent,
   isScalarContent,
   isStringDiffContent,
+  isDescriptionList,
   MultiModalResponse,
   ToolbarProps
 } from '@kui-shell/core'
@@ -45,6 +46,7 @@ import HTMLString from './HTMLString'
 import HTMLDom from './Scalar/HTMLDom'
 import { KuiContext } from '../../'
 import RadioTableSpi from '../spi/RadioTable'
+import DescriptionList from '../spi/DescriptionList'
 
 export type KuiMMRProps = ToolbarProps & {
   tab: KuiTab
@@ -140,6 +142,14 @@ export default class KuiContent extends React.PureComponent<KuiMMRProps, State>
     } else if (isScalarContent(mode)) {
       if (isReactProvider(mode)) {
         return mode.react({ willUpdateToolbar })
+      } else if (isDescriptionList(mode.content)) {
+        return (
+          <div className="flex-fill flex-layout flex-align-stretch">
+            <div className="scrollable scrollable-auto scrollable-x flex-fill flex-layout flex-align-stretch">
+              <DescriptionList groups={mode.content.spec.groups} className="left-pad right-pad" />
+            </div>
+          </div>
+        )
       } else if (isRadioTable(mode.content)) {
         const radioTable = mode.content
         // ^^^ Notes: Even though isRadioTable(mode.content) checks the type of mode.content,

plugins/plugin-client-common/src/components/Views/Sidecar/TopNavSidecarV2.tsx

@@ -97,7 +97,7 @@ export function getStateFromMMR(tab: KuiTab, response: MultiModalResponse): Hist
 
   // toolbarText: if the default mode specified one, then use it;
   // otherwise, use the one specified by response
-  const toolbarText = tabs[defaultMode] ? tabs[defaultMode].toolbarText : response.toolbarText
+  const toolbarText = (tabs[defaultMode] && tabs[defaultMode].toolbarText) || response.toolbarText
 
   return {
     currentTabIndex: defaultMode,

plugins/plugin-client-common/src/components/Views/Terminal/Block/Input.tsx

@@ -710,7 +710,10 @@ export default class Input extends InputProvider {
   private experimentalTag() {
     if (this.props.isExperimental) {
       return (
-        <span className="kui--repl-block-right-element left-pad kui--repl-block-experimental-tag-wrapper">
+        <span
+          className="kui--repl-block-right-element left-pad kui--repl-block-experimental-tag-wrapper"
+          key="experimental-tag"
+        >
           <Tag spanclassname="kui--repl-block-experimental-tag" title={strings('HoverExperimentalTag')} type="warning">
             {strings('ExperimentalTag')}
           </Tag>
@@ -755,7 +758,7 @@ export default class Input extends InputProvider {
   /** spinner for processing blocks */
   private spinner() {
     return (
-      <span className="kui--repl-block-spinner">
+      <span className="kui--repl-block-spinner" key="spinner">
         <Spinner />
       </span>
     )

plugins/plugin-client-common/src/components/spi/DescriptionList/impl/PatternFly.tsx

@@ -0,0 +1,69 @@
+/*
+ * Copyright 2021 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React from 'react'
+import {
+  DescriptionList,
+  DescriptionListGroup,
+  DescriptionListTerm,
+  DescriptionListDescription
+} from '@patternfly/react-core'
+
+import Props from '../model'
+
+import '../../../../../web/scss/components/DescriptionList/PatternFly.scss'
+
+function columnModifier(maxWidth: number) {
+  if (maxWidth > 40) {
+    return {
+      default: '1Col' as const,
+      lg: '2Col' as const,
+      xl: '2Col' as const
+    }
+  } else {
+    return {
+      default: '1Col' as const,
+      lg: '2Col' as const,
+      xl: '3Col' as const
+    }
+  }
+}
+
+export default function PatternFlyDescriptionList(props: Props) {
+  const maxWidth = props.groups.reduce(
+    (max, group) => Math.max(max, group.term.length /*, group.description.toString().length */),
+    0
+  )
+
+  return (
+    <DescriptionList
+      isAutoColumnWidths
+      className={[props.className, 'kui--description-list', 'flex-fill'].join(' ')}
+      columnModifier={columnModifier(maxWidth)}
+    >
+      {props.groups.map((group, idx) => (
+        <DescriptionListGroup key={idx} className="kui--description-list-group">
+          <DescriptionListTerm className="kui--description-list-term" data-term={group.term}>
+            {group.term}
+          </DescriptionListTerm>
+          <DescriptionListDescription className="kui--description-list-description">
+            {group.description}
+          </DescriptionListDescription>
+        </DescriptionListGroup>
+      ))}
+    </DescriptionList>
+  )
+}

plugins/plugin-client-common/src/components/spi/DescriptionList/index.tsx

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2021 The Kubernetes Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import React from 'react'
+import Props from './model'
+
+const PatternFly4 = React.lazy(() => import('./impl/PatternFly'))
+
+export { Props }
+
+export default function DescriptionListSpi(props: Props): React.ReactElement {
+  return <PatternFly4 {...props} />
+}