feat(plugins/plugin-client-common): initial support for code block ordering

Author: starpit

packages/test/src/api/Wizard.ts

@@ -24,6 +24,7 @@ export default class Wizard {
   private readonly _navItemProgressStepper = '.kui--progress-stepper'
   private readonly _navItemProgressStep = '.kui--progress-step'
   private readonly _body = '.pf-c-wizard__main-body'
+  private readonly _wizardProgressMeasure = '.pf-c-progress__measure'
 
   public withTitle(title: string) {
     return `${this.wizard} ${this.title}[aria-label="${title}"]`
@@ -60,4 +61,8 @@ export default class Wizard {
   public navItemProgressStep(navIdx: number, stepIdx: number) {
     return `${this.navItemProgressSteps(navIdx)}:nth-child(${stepIdx + 1})`
   }
+
+  public get progressMeasure() {
+    return `${this.wizard} ${this._wizardProgressMeasure}`
+  }
 }

plugins/plugin-client-common/i18n/code_en_US.json

@@ -1,7 +1,11 @@
 {
   "Code Block": "Code Block",
+  "Optional Code Block": "Code Block *(this code block is optional)*",
 
   "xOfy": "{0} of {1}",
+  "xOfyFailingz": "{0} of {2} ({1} failure)",
+  "xOfyFailingsz": "{0} of {2} ({1} failures)",
+
   "Completed tasks": "Completed tasks",
 
   "status.blank": "Not yet executed",

plugins/plugin-client-common/src/components/Content/Markdown/components/Wizard/CodeBlockProps.ts

@@ -18,5 +18,26 @@ export default interface CodeBlockProps {
   id: string
   body: string
   language: string
+  optional?: boolean
   validate?: string
+
+  /**
+   * Is this a member of a group of choices? e.g. am I `A` in a choice
+   * to do either `A+B` or `C+D`?
+   */
+  choice?: {
+    /**
+     * This option names the group, to keep it distinct from other
+     * groups of choices.
+     */
+    group?: string
+
+    /**
+     * This option names that member. e.g. if the user can choose
+     * between doing either A-and-B or C-and-D, this identifies
+     * whether we are part ofth e first choice (A+B) or the second
+     * (C+D).
+     */
+    member?: string
+  }
 }

plugins/plugin-client-common/src/components/Content/Markdown/components/Wizard/Progress.tsx

@@ -17,20 +17,22 @@
 import React from 'react'
 import { i18n } from '@kui-shell/core'
 
-import CodeBlockProps from './CodeBlockProps'
+import { Graph, blocks, progress } from '../code/graph'
 
 import { ProgressStepState, statusFromStatusVector } from '../../../ProgressStepper'
 import { subscribeToLinkUpdates, unsubscribeToLinkUpdates } from '../../../LinkStatus'
 
+import { State as WizardState } from '.'
+
 import { ProgressVariant } from '@patternfly/react-core'
 
 const PatternFlyProgress = React.lazy(() => import('@patternfly/react-core').then(_ => ({ default: _.Progress })))
 
 const strings = i18n('plugin-client-common', 'code')
 
-interface Props {
+type Props = Pick<WizardState, 'choices'> & {
   /** The tasks to be accomplished */
-  codeBlocks: CodeBlockProps[]
+  codeBlocks: Graph
 }
 
 type Status = ProgressStepState['status']
@@ -65,52 +67,35 @@ export default class Progress extends React.PureComponent<Props, State> {
   }
 
   public componentDidMount() {
-    this.props.codeBlocks.forEach(_ => {
+    blocks(this.props.codeBlocks, 'all').forEach(_ => {
       subscribeToLinkUpdates(_.id, this._statusUpdateHandler)
     })
   }
 
   public componentWillUnmount() {
-    this.props.codeBlocks.forEach(_ => {
+    blocks(this.props.codeBlocks, 'all').forEach(_ => {
       unsubscribeToLinkUpdates(_.id, this._statusUpdateHandler)
     })
   }
 
   private get nSteps() {
-    return this.props.codeBlocks.length
+    return progress(this.props.codeBlocks, undefined, this.props.choices).nTotal
   }
 
   private counts() {
-    return Object.values(this.state.status).reduce(
-      (counts, status) => {
-        if (status === 'success') {
-          counts.nDone++
-        } else if (status === 'error') {
-          counts.nError++
-        } else if (status === 'in-progress') {
-          counts.nInProgress++
-        }
-
-        return counts
-      },
-      { nDone: 0, nError: 0, nInProgress: 0 }
-    )
+    return progress(this.props.codeBlocks, this.state.status, this.props.choices)
   }
 
   public render() {
-    const { nDone, nError /* , nInProgress */ } = this.counts()
+    const { nDone, nError } = this.counts()
 
     const title = strings('Completed tasks')
-    const label = /* nInProgress > 0 ? strings('status.in-progress') : */ strings('xOfy', nDone, this.nSteps)
-
-    const variant =
-      nDone === this.nSteps
-        ? ProgressVariant.success
-        : nError > 0
-        ? ProgressVariant.danger
-        : // : nInProgress > 0
-          // ? ProgressVariant.warning
-          undefined
+    const label =
+      nError > 0
+        ? strings(nError === 1 ? 'xOfyFailingz' : 'xOfyFailingsz', nDone, nError, this.nSteps)
+        : strings('xOfy', nDone, this.nSteps)
+
+    const variant = nDone === this.nSteps ? ProgressVariant.success : nError > 0 ? ProgressVariant.danger : undefined
 
     return (
       <PatternFlyProgress

plugins/plugin-client-common/src/components/Content/Markdown/components/Wizard/index.tsx

@@ -20,28 +20,66 @@ import { WizardProps } from './rehype-wizard'
 
 import Progress from './Progress'
 import CodeBlockProps from './CodeBlockProps'
+import { onTabSwitch, offTabSwitch } from '../tabbed'
+import { Graph, sequence, compile, blocks } from '../code/graph'
 
 import Card from '../../../../spi/Card'
-import { MiniProgressStepper, MiniProgressStep } from '../../../MiniProgressStepper'
+import { MiniProgressStepper } from '../../../MiniProgressStepper'
 
 import '../../../../../../web/scss/components/Wizard/PatternFly.scss'
 
 const PatternFlyWizard = React.lazy(() => import('@patternfly/react-core').then(_ => ({ default: _.Wizard })))
 
-export default class Wizard extends React.PureComponent<WizardProps> {
-  private wizardCodeBlockSteps(containedCodeBlocks: CodeBlockProps[]) {
+type Props = WizardProps & { uuid: string }
+
+export interface State {
+  /** Map from tab group to currently selected tab member */
+  choices: Record<string, string>
+}
+
+export default class Wizard extends React.PureComponent<Props, State> {
+  private readonly cleaners: (() => void)[] = []
+
+  public constructor(props: Props) {
+    super(props)
+
+    this.state = {
+      choices: {}
+    }
+  }
+
+  public componentDidMount() {
+    const switcher = (group: string, member: string) => {
+      this.setState(curState => ({
+        choices: Object.assign({}, curState.choices, { [group]: member })
+      }))
+    }
+
+    onTabSwitch(this.props.uuid, switcher)
+    this.cleaners.push(() => offTabSwitch(this.props.uuid, switcher))
+  }
+
+  public componentDidUnmount() {
+    this.cleaners.forEach(_ => _())
+  }
+
+  private wizardCodeBlockSteps(containedCodeBlocks: Graph) {
     return (
-      containedCodeBlocks.length > 0 && (
-        <MiniProgressStepper>
-          {containedCodeBlocks.map((_, idx) => (
-            <MiniProgressStep key={idx} codeBlockId={_.id} validate={_.validate} body={_.body} language={_.language} />
-          ))}
-        </MiniProgressStepper>
+      containedCodeBlocks && (
+        <MiniProgressStepper
+          steps={blocks(containedCodeBlocks, this.state.choices).map(_ => ({
+            codeBlockId: _.id,
+            validate: _.validate,
+            body: _.body,
+            language: _.language,
+            optional: _.optional
+          }))}
+        />
       )
     )
   }
 
-  private wizardStepDescription(description: string, containedCodeBlocks: CodeBlockProps[]) {
+  private wizardStepDescription(description: string, containedCodeBlocks: Graph) {
     return (
       <div className="kui--wizard-nav-item-description">
         {this.wizardCodeBlockSteps(containedCodeBlocks)}
@@ -50,14 +88,16 @@ export default class Wizard extends React.PureComponent<WizardProps> {
     )
   }
 
-  private containedCodeBlocks(_: WizardProps['children'][0]): CodeBlockProps[] {
+  private containedCodeBlocks(_: WizardProps['children'][0]): Graph {
     if (typeof _.props.containedCodeBlocks === 'string' && _.props.containedCodeBlocks.length > 0) {
-      return _.props.containedCodeBlocks
-        .split(' ')
-        .filter(Boolean)
-        .map(_ => JSON.parse(Buffer.from(_, 'base64').toString()) as CodeBlockProps)
+      return compile(
+        _.props.containedCodeBlocks
+          .split(' ')
+          .filter(Boolean)
+          .map(_ => JSON.parse(Buffer.from(_, 'base64').toString()) as CodeBlockProps)
+      )
     } else {
-      return []
+      return undefined
     }
   }
 
@@ -72,11 +112,11 @@ export default class Wizard extends React.PureComponent<WizardProps> {
   /** Overall progress across all steps */
   private progress() {
     if (this.props['data-kui-wizard-progress'] === 'bar') {
-      const codeBlocks = this.children.flatMap(_ => this.containedCodeBlocks(_))
+      const allCodeBlocks = sequence(this.children.flatMap(_ => this.containedCodeBlocks(_)))
       return (
-        codeBlocks.length > 0 && (
+        allCodeBlocks.sequence.length > 0 && (
           <div className="kui--markdown-major-paragraph">
-            <Progress codeBlocks={codeBlocks} />
+            <Progress choices={this.state.choices} codeBlocks={allCodeBlocks} />
           </div>
         )
       )

plugins/plugin-client-common/src/components/Content/Markdown/components/code/README.md

@@ -0,0 +1,34 @@
+# Markdown Code Block Handling
+
+## Execution Ordering Constraints
+
+- markdown tabs represent an exclusive set of options
+  - code blocks within a tab must be executed sequentially
+- code blocks within a wizard step can be executed in any order
+- across wizard steps, the groups of code blocks in each step must be executed sequentially in the order of the wizard steps
+
+```
+  *************
+  Wizard Step 1
+      CodeA
+  *************
+
+  *************
+  Wizard Step 2
+
+  |Tab1 | | Tab 2 |
+    CodeB   CodeC
+            CodeD
+            CodeE
+  *************
+
+  *************
+  Wizard Step 3
+      CodeF
+  *************
+```
+
+Under those rules, a partial ordering of this markdown is:
+
+    CodeA -> CodeB                    -> CodeF
+         \-> CodeC -> CodeD -> CodeE  -/

plugins/plugin-client-common/src/components/Content/Markdown/components/code/dump.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2022 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.
+ */
+
+/** Re-serialize the given attributes and code block body */
+export default function dump(attributes: Record<string, any>, body: string) {
+  return `
+---
+${require('js-yaml').dump(attributes)}
+---
+${body}
+`
+}