HTML5 obsoletes framesets. The classhelp system is based on
framesets.

We have a number of issues associated with the classhelp system
that can be fixed by a replacement:

  issue 2550580 - Missing support for radio buttons in user.help.html
  issue 2550939 - Refactor use of javascript in templates to support Content Security Policy 
(CSP)
  issue 2550656 - with more than 50 items, the simple classhelp javascript windows do not 
allow to select from all items (affects keywords, superceder)
  issue 2551231 - template.py-HTMLClass::classhelp doesn't merge user defined classes

In addition to fixing the above, it should support the calendar
popup.

I see three major modes of operation:

  1) info display - used to display a class and
     descriptions. E.G.  a list of all priorities and
     descriptions of them. No interaction with the original
     form. This does not require javascript. (Used when classhelp
     is invoked without the property parameter.)

  2) display first - just display the items and allow the user to
     select one or more via checkboxes. Determined by the
     class.template not including a search option. This case
     includes clicking links in a calendar popup.

  3) search first - have the user search using criteria (user's
     partial username, user's partial real name, issue title,...)

The current frames based implementation uses target="_blank" to
popup the help in a new window/tab.

For the info display mode that is an option that I would like to
keep as it doesn't require javascript. This makes info display
work if javascript is disabled or it is used with text based or
non-javascript capable browsers.  If javascript is available it
can be displayed in a popup the same as the other two
modes. (Note displaying in a popup requires a way to dismiss it
as there is no browser window/tab to close.)

The other two modes require javascript to set the original field
to the values in the classhelp. So using _blank is not a
constraint for the redesign of these modes. A modal or non-modal
(possibly movable) popup displayed using javascript can be
used. (See below for displaying the trigger only when javascript
is available.)

The popup modal/non-modal content should be defined by a template
(similar to @template=help currently). For the 'display first'
mode the template has the following sections:

   <div id="help-select"> - the container where the table is
   built.  The table has a checkbox (or radiobutton) to select
   item(s).

   Below #help-select is prev/next navigation if it is a list and
   the size is larger than @pagesize. Clicking on these links,
   manipulates the contents of #help-select (via innerHTML)
   without refreshing the window. When these links are checked,
   the input list should be preserved. This allows accumulating
   selected items across multiple pages. When doing multiple
   selection, selected items in the input should be checked if
   shown (see below for server side support).

   <div id="help-confirmation"> - Consists of an input that holds
   a comma separated list of selected (checked) items.  It is a
   form that has a submit button that sets the property in the
   original page. This is optional for single select things like
   calendar or type="radiobutton". In these cases update the
   related property and close (maybe optional) help window on
   change event.

For the 'search first' option, the template should add:

   A search form to search by criteria.

   Submitting the form is captured by javascript and submitted to
   the server's @template=help-select template. The returned HTML
   fragment is injected into the <div id="help-select"> with
   innerHTML. (Assumption: the help-select template produces safe
   escaped html suitable for innerHTML). Also this can be
   triggered multiple times and should not erase the current
   input field at the bottom of the page.

   The rest of the elements for the display first case completes
   the template.

The javascript for the checkboxes/radiobuttons should not use onX
(onclick ...) handlers in the html to comply with CSP. Ideally
add one event listener for the 'change' event to append/remove
checkbox changes from the input or set/close the help window for
a radiobutton to the div.#help-select.

For links, the current calendar encodes the date into the
generated onclick handler. Instead generate a
data-value="2023-02-24" attribute to record the datestamp. Use
that from the javascript click handler for the calendar.

Open questions:

  How should current values in the original form be represented
    in the help box?

    calendar: the calendar should include the earliest (if more
      than 1) date in the form's property. It should show the
      current month if no date is selected. Do this on the server
      by sending the the current date value
      (e.g. @currentValue="2023-10-22") in the GET request.

    single select: should the displayed help page include the
      selected item? If the list is short enough to fit in a
      single page, it will.

      If there are multiple pages, start at page 1 even if the
      item is not on the page. When the next/prev buttons are
      used, and the item is on the page, it should be marked
      selected by the server by sending the current value (via
      @currentValue="23" for example) in the GET request.

    multiple select: when opening save the original field's
      values in the input on the help page. Send via current
      value to the server to have these items selected in the
      response (question will the URL get too long if there are
      lots of items?). Do not add/delete any item from the input
      unless it is checked/unchecked.

 Should the input field for multiselect be read-only so changes
   to it can only be done by check/uncheck? This would remove the
   need to watch for changes (onblur) to the input to sync the
   checked/unchecked state of matching items. (My initial answer
   is allow editing and if the checklist is out of sync, that's
   fine. When adding either add blindly (the back end will
   collapse duplicates), or check the list for a match and ignore
   add if present. When removing, a missing match should be
   silently ignored.


-----

Since the "display first" and "search first" modes require
javascript, it would be nice to hide the invoking link if
javascript is not present.

Consider:

       db.priority.classhelp('id,name,description', width='600')

would produce:

  <a class="classhelp"
     href="priority?
@template=help&properties=id,name,description&form=formName&type=checkbox&@sort=order&@pagesiz
e=50" target="_blank">(list)</span>

Using:

  db.user.classhelp('username,realname,address', property='nosy', width='600')

would produce HTML like:

  <a class="classhelp missing_js"
     href="user?
@template=help&properties=username,realname,address&property=nosy&form=itemSynopsis&type=check
box&@sort=username&@pagesize=50"
     >(list)</span>

with CSS 'a.classhelp.missing_js { visibility: hidden; }'. I used
visibility:hidden rather than display:none to prevent layout
shifts. When flexbox/grid is used there is an element there to
take up the position.

When the page is loaded a function like:

  document.querySelectorAll('a.classhelp.missing_js').forEach(
     (a) => {a.classList.remove('missing_js')}

removes the missing_js class to allow the link to be seen.

(The above should be implemented as part of progressive
enhancement.  An admin can choose to implement something that
works on more limited devices. S/he can replace the link with an
empty span in the server response. The browser can signal the
server that it does not have js. The server can see this and act
accordingly.  This would work in CSS challenged browsers as well.
See: https://wiki.roundup-tracker.org/IsJavascriptAvailable. This
is something for the admin to implement in the template if
desired. This is out of scope for this ticket.)

see also issue 2551291