foreman_theme_satellite 16.4.2 → 16.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54d89d60344083fcf31950dec0172c89165a903d4a1fe3ab06bf8eeaa3b88840
-  data.tar.gz: 2ddc9af30171ffc58074c56b064b595294145142f79f4034ec7110f6239c71e0
+  metadata.gz: 0f4492cd1ca5ab22e180b6767695d8a7d7d029915018c5214dd257dfbc1009c8
+  data.tar.gz: 593d0c39829ac5c5f2bd889c23baa151d0e824da8257510eea8238bf935f833b
 SHA512:
-  metadata.gz: 332f7a55cbb67c6a4733cb34e44d14b803a1265b00fad689c9101e7b6b6ee4f7b5fee5e11286e2d6d7833271cf8a9dc834050fd32a698c524311ad1da1f53b77
-  data.tar.gz: 6ff2275c254713a345914fddd26138053ed6b5b4b855f75ddcbe2266480746646753324cb67c916efb7c0be0c1d163a04d4b7ec87003d781e8817f62c6a1da0c
+  metadata.gz: 6e4089ace8320b932eb4e1a49dca2ee34e61125284a2e996b54f6621568337f9e863342350cc31b5caaf09c531b7ff0398e07ca3ee1a5d8330eb8ea2c02c31fe
+  data.tar.gz: 1fdfde63ecab76fc18516aaf11fab2d6808426b5594526caaa8c9313ba8292dfaccc0137db517892b6445220dc0141fc3839b8632673ff71167b95a87eda93ca

data/README.md

@@ -73,11 +73,18 @@ that will be branded automatically to
 Many times we need to use a downstream link instead of an upstream one. The most
 common example for this is pointing to a documentation link.
 
-All links to documentation in Foreman are local and redirected to
-`links_controller`. This controller is prepended with
-`documentation_controller_branding` concern that uses dictionary stored in
-`lib/foreman_theme_satellite/documentation.rb` to redirect documentation to
-downstream URLs.
+Documentation controls are hidden by this theme. Inline documentation links remain
+visible, and the `manual`, `docs`, `plugin_manual`, `wiki`, and upgrade documentation
+routes redirect to the configured Satellite version's landing page:
+`{base}/en/documentation/red_hat_satellite/{version}`. The base comes from the
+`satellite_documentation_url` setting, including offline documentation servers.
+Direct Satellite documentation links in the page are rewritten to `/links/manual`
+(with the application's URL prefix). Support and the upgrade helper keep their
+existing destinations.
+
+The detailed mappings in `lib/foreman_theme_satellite/documentation.rb` are retained
+for future restoration, but these redirects currently bypass them. The mapping
+examples below describe that retained mechanism, not the active redirect behavior.
 
 In foreman:
 ``` ruby

data/app/assets/stylesheets/foreman_theme_satellite/documentation.scss

@@ -0,0 +1,12 @@
+// Hide identified standalone controls only. Do not match hrefs: welcome
+// pages use those same /links destinations inside sentences.
+.satellite-documentation-hidden,
+.docs-element-to-remove,
+[data-ouia-component-id="doc-url-dropdown"],
+[data-ouia-component-id="action-buttons-documentation"],
+[data-ouia-component-id="register-host-documentation-button"],
+[data-ouia-component-id="audits-documentation-button"],
+[data-ouia-component-id="inventory-documentation-button"],
+[data-ouia-component-id="upgrade-docs-button"] {
+  display: none !important;
+}

data/app/assets/stylesheets/foreman_theme_satellite/foreman_theme_satellite.css

@@ -1 +1,2 @@
 //= require foreman_theme_satellite/theme
+//= require foreman_theme_satellite/documentation

data/app/controllers/concerns/documentation_controller_branding.rb

@@ -3,6 +3,19 @@ require_relative '../../../lib/foreman_theme_satellite/documentation'
 module DocumentationControllerBranding
   extend ActiveSupport::Concern
 
+  # Keep the detailed mappings below for future restoration. All public
+  # documentation redirects currently land on the configured version's index.
+  def external_url(type:, options: {})
+    documentation_redirect = %w[manual docs plugin_manual wiki].include?(type.to_s)
+    upgrade_documentation_redirect = type.to_s == 'upgrade' && options[:section] == 'documentation'
+
+    if documentation_redirect || upgrade_documentation_redirect
+      documentation_root_url
+    else
+      super
+    end
+  end
+
   def documentation_url(section = nil, options = {})
     url = ''
     unless section.nil?
@@ -55,12 +68,10 @@ module DocumentationControllerBranding
     "#{unversioned_documentation_root}/#{ForemanThemeSatellite.documentation_version}"
   end
 
-  def documentation_root
-    "#{unversioned_documentation_root}/#{ForemanThemeSatellite.documentation_version}/html-single"
-  end
+  alias_method :documentation_root, :documentation_root_url
 
   def unversioned_documentation_root
-    "#{Setting[:satellite_documentation_url]}/documentation/en-us/red_hat_satellite"
+    "#{Setting[:satellite_documentation_url]}/en/documentation/red_hat_satellite"
   end
 
   private

data/app/helpers/documentation_visibility_helper.rb

@@ -0,0 +1,30 @@
+# Hide Rails documentation controls without changing their URL helpers or redirects.
+module DocumentationVisibilityHelper
+  DOCUMENTATION_URL_TO_REMOVE = '#satellite-documentation-link-to-remove'.freeze
+  DOCUMENTATION_ELEMENT_TO_REMOVE_CLASS = 'docs-element-to-remove'.freeze
+  DOCUMENTATION_SECTIONS_TO_REMOVE = %w[
+    4.1.1LDAPAuthentication
+    5.7ExternalAuthentication
+  ].freeze
+
+  def help_button
+    ''
+  end
+
+  def documentation_button(*_args, **_options)
+    ''
+  end
+
+  def documentation_url(section = nil, *args, **options)
+    return DOCUMENTATION_URL_TO_REMOVE if DOCUMENTATION_SECTIONS_TO_REMOVE.include?(section.to_s)
+
+    super
+  end
+
+  def link_to(name = nil, options = nil, html_options = nil, &block)
+    link_options = block_given? ? name : options
+    return tag.div(class: DOCUMENTATION_ELEMENT_TO_REMOVE_CLASS) if link_options == DOCUMENTATION_URL_TO_REMOVE
+
+    super
+  end
+end

data/app/overrides/hide_documentation.rb

@@ -0,0 +1,23 @@
+Deface::Override.new(
+  virtual_path: 'foreman_puppet/config_groups/welcome',
+  name: 'satellite_hide_config_groups_documentation',
+  replace: "erb[loud]:contains('EmptyState')",
+  text: <<~ERB
+    <%= react_component('EmptyState', {
+                                        :icon => 'object-group',
+                                        :iconType => 'fa',
+                                        :header => _('Config Groups'),
+                                        :description => description,
+                                        :action => action
+                                      }) %>
+  ERB
+)
+
+Deface::Override.new(
+  virtual_path: 'foreman_puppet/environments/welcome',
+  name: 'satellite_hide_environments_documentation',
+  replace: "erb[loud]:contains('WelcomeEnv')",
+  text: <<~ERB
+    <%= react_component('SatelliteWelcomeEnv', {canCreate: authorized_for(action: :new)}) %>
+  ERB
+)

data/lib/foreman_theme_satellite/engine.rb

@@ -102,6 +102,7 @@ module ForemanThemeSatellite
 
         UINotifications::StringParser.send :prepend, DeprecationNotification::StringParser
         Notification.singleton_class.send :prepend, DeprecationNotification::Notification
+        ApplicationHelper.prepend DocumentationVisibilityHelper
         LinksController.prepend DocumentationControllerBranding
         ProvisioningTemplatesController.include ProvisioningTemplatesControllerBranding
         ProvisioningTemplatesHelper.prepend ProvisioningTemplatesHelperBranding

data/lib/foreman_theme_satellite/version.rb

@@ -1,3 +1,3 @@
 module ForemanThemeSatellite
-  VERSION = '16.4.2'.freeze
+  VERSION = '16.4.3'.freeze
 end

data/webpack/components/SatelliteWelcomeEnv.js

@@ -0,0 +1,54 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { FormattedMessage } from 'react-intl';
+import { translate as __ } from 'foremanReact/common/I18n';
+import { foremanUrl, getManualURL } from 'foremanReact/common/helpers';
+import EmptyState from 'foremanReact/components/common/EmptyState';
+
+export const SatelliteWelcomeEnv = ({ canCreate }) => {
+  const action = canCreate && {
+    title: __('Create Puppet Environment'),
+    url: foremanUrl('/foreman_puppet/environments/new'),
+  };
+
+  const description = (
+    <FormattedMessage
+      id="puppetenv-welcome"
+      defaultMessage={__(
+        'If you are planning to use Foreman as an external node classifier you should provide information about one or more environments.{newLine}This information is commonly imported from a pre-existing Puppet configuration by the use of the {puppetClassesLinkToDocs} and environment importer.'
+      )}
+      values={{
+        newLine: <br />,
+        puppetClassesLinkToDocs: (
+          <a
+            target="_blank"
+            href={getManualURL('4.2.2Classes')}
+            rel="noreferrer"
+          >
+            {__('Puppet classes')}
+          </a>
+        ),
+      }}
+    />
+  );
+
+  return (
+    <EmptyState
+      icon="th"
+      iconType="fa"
+      header={__('Puppet Environments')}
+      description={description}
+      action={action}
+    />
+  );
+};
+
+SatelliteWelcomeEnv.propTypes = {
+  canCreate: PropTypes.bool,
+};
+
+SatelliteWelcomeEnv.defaultProps = {
+  canCreate: false,
+};
+
+export default SatelliteWelcomeEnv;

data/webpack/components/fills/UpgradePage/SatelliteUpgradeHelperCard.js

@@ -1,6 +1,12 @@
 import React from 'react';
 
-import { Card, CardBody, CardTitle, CardFooter, Button } from '@patternfly/react-core';
+import {
+  Card,
+  CardBody,
+  CardTitle,
+  CardFooter,
+  Button,
+} from '@patternfly/react-core';
 import { ExternalLinkSquareAltIcon } from '@patternfly/react-icons';
 
 import { translate as __ } from 'foremanReact/common/I18n';
@@ -10,8 +16,10 @@ const SatelliteUpgradeHelperCard = () => (
   <Card ouiaId="upgrade-docs-satellite-helper" isFlat>
     <CardTitle component="h4">{__('Satellite upgrade helper')}</CardTitle>
     <CardBody>
-      {__('Generate a customized upgrade plan based on your current Satellite environment.' +
-      ' This tool will guide you through the upgrade process and provide additional steps to avoid known issues specific to your upgrade scenario.')}
+      {__(
+        'Generate a customized upgrade plan based on your current Satellite environment.' +
+          ' This tool will guide you through the upgrade process and provide additional steps to avoid known issues specific to your upgrade scenario.'
+      )}
     </CardBody>
     <CardFooter>
       <Button

data/webpack/documentation/documentationMenuKeyboard.js

@@ -0,0 +1,89 @@
+// PatternFly's legacy dropdown keeps references to CSS-hidden items. Handle
+// navigation in affected menus before its handler attempts to focus those refs.
+const navigationKeys = ['ArrowDown', 'ArrowUp', 'Home', 'End'];
+const openingKeys = [...navigationKeys, 'Enter', ' '];
+const dropdownSelector = '.pf-v5-c-dropdown';
+const menuSelector = '.pf-v5-c-dropdown__menu';
+const itemSelector = '[role="menuitem"]';
+
+const isVisible = node => {
+  const { defaultView } = node.ownerDocument;
+  for (let ancestor = node; ancestor; ancestor = ancestor.parentElement) {
+    const style = defaultView.getComputedStyle(ancestor);
+    if (
+      ancestor.hidden ||
+      style.display === 'none' ||
+      style.visibility === 'hidden'
+    ) {
+      return false;
+    }
+  }
+  return true;
+};
+
+export default function installMenuKeyboard(doc, isDocumentationControl) {
+  const frames = new Set();
+  const navigate = (dropdown, key, current) => {
+    const menu = dropdown.querySelector(menuSelector);
+    if (!menu || !isVisible(menu)) return false;
+    const items = [...menu.querySelectorAll(itemSelector)];
+    if (!items.some(isDocumentationControl)) return false;
+    const available = items.filter(
+      item =>
+        !isDocumentationControl(item) &&
+        !item.hasAttribute('disabled') &&
+        item.getAttribute('aria-disabled') !== 'true' &&
+        isVisible(item)
+    );
+    const lastIndex = available.length - 1;
+    const currentIndex = available.indexOf(current);
+    let nextIndex = 0;
+    if (key === 'End' || (key === 'ArrowUp' && currentIndex <= 0)) {
+      nextIndex = lastIndex;
+    } else if (key === 'ArrowUp') {
+      nextIndex = currentIndex - 1;
+    } else if (key === 'ArrowDown' && currentIndex >= 0) {
+      nextIndex = (currentIndex + 1) % available.length;
+    }
+    const target =
+      available[nextIndex] || dropdown.querySelector('[aria-expanded]');
+    if (target) target.focus();
+    return true;
+  };
+
+  const handleEvent = event => {
+    const dropdown = event.target.closest(dropdownSelector);
+    if (!dropdown) return;
+    const toggle = event.target.closest('[aria-expanded]');
+    const key = event.type === 'click' ? 'Enter' : event.key;
+    if (event.type === 'keydown' && navigationKeys.includes(key)) {
+      const current = event.target.closest(itemSelector);
+      if (navigate(dropdown, key, current)) {
+        event.preventDefault();
+        event.stopImmediatePropagation();
+        return;
+      }
+    }
+    if (!toggle || !openingKeys.includes(key)) return;
+    // Let React open the menu and PatternFly finish its initial focus first.
+    // This also handles menus whose first item is hidden documentation.
+    const frame = doc.defaultView.requestAnimationFrame(() => {
+      frames.delete(frame);
+      if (
+        toggle.isConnected &&
+        toggle.getAttribute('aria-expanded') === 'true'
+      ) {
+        navigate(dropdown, key, null);
+      }
+    });
+    frames.add(frame);
+  };
+
+  doc.addEventListener('keydown', handleEvent, true);
+  doc.addEventListener('click', handleEvent, true);
+  return () => {
+    doc.removeEventListener('keydown', handleEvent, true);
+    doc.removeEventListener('click', handleEvent, true);
+    frames.forEach(frame => doc.defaultView.cancelAnimationFrame(frame));
+  };
+}

data/webpack/documentation/documentationMenuKeyboard.test.js

@@ -0,0 +1,229 @@
+import React, { useState } from 'react';
+import fs from 'fs';
+import path from 'path';
+import {
+  render,
+  fireEvent,
+  screen,
+  waitFor,
+  cleanup,
+} from '@testing-library/react';
+import '@testing-library/jest-dom';
+import {
+  Dropdown,
+  DropdownItem,
+  DropdownToggle,
+  DropdownGroup,
+} from '@patternfly/react-core/deprecated';
+import { ActionButtons } from 'foremanReact/components/PF4/TableIndexPage/ActionButtons';
+import DocumentationLink from 'foremanReact/components/PF4/DocumentationLink';
+import { installDocumentationHiding } from './hideDocumentation';
+
+const styles = fs
+  .readFileSync(
+    path.join(
+      __dirname,
+      '../../app/assets/stylesheets/foreman_theme_satellite/documentation.scss'
+    ),
+    'utf8'
+  )
+  .replace(/^\/\/.*$/gm, '');
+let installation;
+
+beforeEach(() => {
+  const style = document.createElement('style');
+  style.textContent = styles;
+  style.id = 'documentation-test-style';
+  document.head.appendChild(style);
+  installation = installDocumentationHiding(document);
+});
+afterEach(() => {
+  installation.disconnect();
+  cleanup();
+  document.getElementById('documentation-test-style').remove();
+});
+
+// Use the same grouped PatternFly menu and documentation component as bookmarks.
+const BookmarksMenu = () => {
+  const [isOpen, setOpen] = useState(false);
+  return (
+    <Dropdown
+      ouiaId="test-bookmarks"
+      isOpen={isOpen}
+      isGrouped
+      toggle={
+        <DropdownToggle onToggle={(_event, open) => setOpen(open)}>
+          Bookmarks
+        </DropdownToggle>
+      }
+    >
+      <DropdownGroup>
+        <DocumentationLink href="/links/manual" />
+        <DropdownItem ouiaId="saved-bookmark" href="/hosts?search=saved">
+          Saved bookmark
+        </DropdownItem>
+        <DropdownItem ouiaId="disabled-bookmark" isDisabled>
+          Unavailable bookmark
+        </DropdownItem>
+        <DropdownItem ouiaId="manage-bookmarks">Manage bookmarks</DropdownItem>
+      </DropdownGroup>
+    </Dropdown>
+  );
+};
+
+const press = (element, key) =>
+  fireEvent.keyDown(element, {
+    key,
+    keyCode: {
+      ArrowDown: 40,
+      ArrowUp: 38,
+      Home: 36,
+      End: 35,
+      Enter: 13,
+      Escape: 27,
+    }[key],
+  });
+
+test('table dropdown skips documentation and wraps between functional actions', async () => {
+  const refresh = jest.fn();
+  render(
+    <ActionButtons
+      buttons={[
+        { title: 'Create', action: { href: '/hosts/new' } },
+        { title: 'Export', action: { href: '/hosts.csv' } },
+        { title: 'Documentation', action: { href: '/hosts/help' } },
+        { title: 'Refresh', action: { onClick: refresh } },
+      ]}
+    />
+  );
+  const toggle = screen.getByRole('button', { name: 'toggle action dropdown' });
+  toggle.focus();
+  press(toggle, 'Enter');
+  const first = await screen.findByRole('menuitem', { name: 'Export' });
+  const last = screen.getByRole('menuitem', { name: 'Refresh' });
+  await waitFor(() => expect(first).toHaveFocus());
+  await waitFor(() =>
+    expect(
+      screen.queryByRole('menuitem', { name: 'Documentation' })
+    ).not.toBeInTheDocument()
+  );
+  press(first, 'ArrowDown');
+  expect(last).toHaveFocus();
+  press(last, 'ArrowDown');
+  expect(first).toHaveFocus();
+  press(first, 'ArrowUp');
+  expect(last).toHaveFocus();
+  press(last, 'Home');
+  expect(first).toHaveFocus();
+  press(first, 'End');
+  expect(last).toHaveFocus();
+  press(last, 'Enter');
+  expect(refresh).toHaveBeenCalledTimes(1);
+  press(last, 'Escape');
+  await waitFor(() => expect(toggle).toHaveFocus());
+  expect(toggle).toHaveAttribute('aria-expanded', 'false');
+});
+
+test.each(['Enter', ' '])(
+  'opening with %s skips a hidden first item',
+  async (key) => {
+    render(<BookmarksMenu />);
+    const toggle = screen.getByRole('button', { name: 'Bookmarks' });
+    toggle.focus();
+    press(toggle, key);
+    const first = await screen.findByRole('menuitem', {
+      name: 'Saved bookmark',
+    });
+    await waitFor(() => expect(first).toHaveFocus());
+    expect(
+      screen.queryByRole('menuitem', { name: 'Documentation' })
+    ).not.toBeInTheDocument();
+    press(first, 'ArrowDown');
+    expect(
+      screen.getByRole('menuitem', { name: 'Manage bookmarks' })
+    ).toHaveFocus();
+    press(document.activeElement, 'ArrowDown');
+    expect(first).toHaveFocus();
+  }
+);
+
+test('ArrowUp from the open toggle focuses the last available action', async () => {
+  render(<BookmarksMenu />);
+  const toggle = screen.getByRole('button', { name: 'Bookmarks' });
+  toggle.focus();
+  fireEvent.click(toggle);
+  await waitFor(() =>
+    expect(
+      screen.getByRole('menuitem', { name: 'Saved bookmark' })
+    ).toHaveFocus()
+  );
+  toggle.focus();
+  press(toggle, 'ArrowUp');
+  const last = await screen.findByRole('menuitem', {
+    name: 'Manage bookmarks',
+  });
+  await waitFor(() => expect(last).toHaveFocus());
+});
+
+test('mouse opening also avoids a hidden initial focus target', async () => {
+  render(<BookmarksMenu />);
+  fireEvent.click(screen.getByRole('button', { name: 'Bookmarks' }));
+  await waitFor(() =>
+    expect(
+      screen.getByRole('menuitem', { name: 'Saved bookmark' })
+    ).toHaveFocus()
+  );
+});
+
+test('menus without documentation retain native keyboard handling', async () => {
+  render(
+    <ActionButtons
+      buttons={[
+        { title: 'Create', action: {} },
+        { title: 'Export', action: { href: '/hosts.csv' } },
+        { title: 'Refresh', action: {} },
+      ]}
+    />
+  );
+  const toggle = screen.getByRole('button', { name: 'toggle action dropdown' });
+  fireEvent.click(toggle);
+  const first = await screen.findByRole('menuitem', { name: 'Export' });
+  first.focus();
+  press(first, 'ArrowDown');
+  expect(screen.getByRole('menuitem', { name: 'Refresh' })).toHaveFocus();
+});
+
+test('disconnect removes the theme keyboard listener', async () => {
+  render(<BookmarksMenu />);
+  fireEvent.click(screen.getByRole('button', { name: 'Bookmarks' }));
+  const first = await screen.findByRole('menuitem', { name: 'Saved bookmark' });
+  await waitFor(() => expect(first).toHaveFocus());
+  installation.disconnect();
+  const bubble = jest.fn();
+  document.addEventListener('keydown', bubble);
+  press(first, 'Home');
+  expect(bubble).toHaveBeenCalled();
+  document.removeEventListener('keydown', bubble);
+});
+
+test('a documentation-only menu keeps focus on its toggle and can close', async () => {
+  render(
+    <ActionButtons
+      buttons={[
+        { title: 'Create', action: {} },
+        { title: 'Documentation', action: { href: '/hosts/help' } },
+      ]}
+    />
+  );
+  const toggle = screen.getByRole('button', { name: 'toggle action dropdown' });
+  toggle.focus();
+  press(toggle, 'Enter');
+  await waitFor(() => expect(toggle).toHaveAttribute('aria-expanded', 'true'));
+  await waitFor(() =>
+    expect(screen.queryByRole('menuitem')).not.toBeInTheDocument()
+  );
+  press(toggle, 'ArrowDown');
+  expect(toggle).toHaveFocus();
+  press(toggle, 'Escape');
+  expect(toggle).toHaveAttribute('aria-expanded', 'false');
+});

data/webpack/documentation/hideDocumentation.js

@@ -0,0 +1,173 @@
+import installMenuKeyboard from './documentationMenuKeyboard';
+
+// Hide only identified documentation buttons and menu actions. Leave inline
+// links and their surrounding text intact; never remove nodes owned by React.
+export const hiddenClass = 'satellite-documentation-hidden';
+
+const controlIds = [
+  'doc-url-dropdown',
+  'action-buttons-documentation',
+  'register-host-documentation-button',
+  'audits-documentation-button',
+  'inventory-documentation-button',
+  'upgrade-docs-button',
+];
+
+const controlIdSet = new Set(controlIds);
+
+const controlSelector = controlIds
+  .map(id => `[data-ouia-component-id="${id}"]`)
+  .join(',');
+
+const dropdownItemSelector =
+  '[data-ouia-component-id="action-buttons-dropdown"] [data-ouia-component-id]';
+
+const httpHref = /^https?:\/\//i;
+
+const satelliteDocsPattern = /\/(?:[a-z]{2}(?:-[a-z]{2})?\/documentation|documentation\/[a-z]{2}(?:-[a-z]{2})?)\/red_hat_satellite(?:\/|$)/i;
+
+const isDocumentationControl = (node, documentationLabel) => {
+  const id = node.getAttribute('data-ouia-component-id');
+  if (!id) return false;
+  if (controlIdSet.has(id)) return true;
+  return (
+    id === `${documentationLabel}-dropdown-item` &&
+    node.closest('[data-ouia-component-id="action-buttons-dropdown"]') !== null
+  );
+};
+
+const syncDocumentationControl = (node, documentationLabel) => {
+  if (!node || node.nodeType !== 1) return;
+  if (isDocumentationControl(node, documentationLabel)) {
+    node.classList.add(hiddenClass);
+    return;
+  }
+  if (node.classList.contains(hiddenClass)) node.classList.remove(hiddenClass);
+};
+
+const hideDocumentationIn = (root, documentationLabel) => {
+  if (!root || root.nodeType !== 1) return;
+  syncDocumentationControl(root, documentationLabel);
+  root.querySelectorAll(controlSelector).forEach(node => {
+    node.classList.add(hiddenClass);
+  });
+  const itemId = `${documentationLabel}-dropdown-item`;
+  root.querySelectorAll(dropdownItemSelector).forEach(node => {
+    if (node.getAttribute('data-ouia-component-id') === itemId) {
+      node.classList.add(hiddenClass);
+    }
+  });
+};
+
+export const hideDocumentation = (
+  doc,
+  documentationLabel = 'Documentation'
+) => {
+  // Recalculate so a React node reused for a functional link becomes visible.
+  doc
+    .querySelectorAll(`.${hiddenClass}`)
+    .forEach(node => node.classList.remove(hiddenClass));
+  hideDocumentationIn(doc.documentElement || doc, documentationLabel);
+};
+
+const normalizeLink = (link, landingPath) => {
+  const href = link.getAttribute('href');
+  // A rewrite sets href to the landing path and the observer hears that
+  // write. Matching it here makes the follow-up a no-op.
+  if (!href || href === landingPath || !httpHref.test(href)) return;
+  let url;
+  try {
+    url = new URL(href);
+  } catch (error) {
+    return;
+  }
+  if (satelliteDocsPattern.test(url.pathname)) {
+    link.setAttribute('href', landingPath);
+  }
+};
+
+const normalizeIn = (root, landingPath) => {
+  if (!root || root.nodeType !== 1) return;
+  if (typeof root.matches === 'function' && root.matches('a[href]')) {
+    normalizeLink(root, landingPath);
+  }
+  root.querySelectorAll('a[href]').forEach(link => {
+    normalizeLink(link, landingPath);
+  });
+};
+
+// Direct Satellite documentation links bypass LinksController. Send them
+// through its landing redirect too, including links in stored notifications.
+export const normalizeSatelliteDocumentation = (doc, landingPath) => {
+  normalizeIn(doc.documentElement || doc, landingPath);
+};
+
+export const installDocumentationHiding = (
+  doc,
+  documentationLabel = 'Documentation',
+  landingPath
+) => {
+  hideDocumentation(doc, documentationLabel);
+  if (landingPath) normalizeSatelliteDocumentation(doc, landingPath);
+
+  const removeMenuKeyboard = installMenuKeyboard(doc, node =>
+    isDocumentationControl(node, documentationLabel)
+  );
+  const pending = [];
+  let scheduled = false;
+  const flush = () => {
+    scheduled = false;
+    const batch = pending.splice(0);
+    batch.forEach(change => {
+      if (change.type === 'childList') {
+        change.added.forEach(node => {
+          hideDocumentationIn(node, documentationLabel);
+          if (landingPath) normalizeIn(node, landingPath);
+        });
+        return;
+      }
+      if (change.name === 'href') {
+        if (
+          landingPath &&
+          change.target.nodeType === 1 &&
+          change.target.matches('a[href]')
+        ) {
+          normalizeLink(change.target, landingPath);
+        }
+        return;
+      }
+      syncDocumentationControl(change.target, documentationLabel);
+    });
+  };
+
+  const observer = new doc.defaultView.MutationObserver(mutations => {
+    mutations.forEach(mutation => {
+      if (mutation.type === 'childList') {
+        if (mutation.addedNodes.length === 0) return;
+        pending.push({ type: 'childList', added: [...mutation.addedNodes] });
+        return;
+      }
+      pending.push({
+        type: 'attributes',
+        name: mutation.attributeName,
+        target: mutation.target,
+      });
+    });
+    if (scheduled || pending.length === 0) return;
+    scheduled = true;
+    doc.defaultView.requestAnimationFrame(flush);
+  });
+  observer.observe(doc.body, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: ['data-ouia-component-id', 'href'],
+  });
+  return {
+    disconnect: () => {
+      observer.disconnect();
+      pending.length = 0;
+      removeMenuKeyboard();
+    },
+  };
+};

data/webpack/documentation/hideDocumentation.test.js

@@ -0,0 +1,294 @@
+import assert from 'assert';
+import fs from 'fs';
+import path from 'path';
+import {
+  hideDocumentation,
+  hiddenClass,
+  normalizeSatelliteDocumentation,
+  installDocumentationHiding,
+} from './hideDocumentation';
+
+const styles = fs
+  .readFileSync(
+    path.join(
+      __dirname,
+      '../../app/assets/stylesheets/foreman_theme_satellite/documentation.scss'
+    ),
+    'utf8'
+  )
+  .replace(/^\/\/.*$/gm, '');
+const createDOM = (html) => {
+  document.head.innerHTML = `<style>${styles}</style>`;
+  document.body.innerHTML = html;
+};
+afterEach(() => {
+  document.head.innerHTML = '';
+  document.body.innerHTML = '';
+  jest.restoreAllMocks();
+});
+
+test('hides documentation controls but preserves inline links, sentences and actions', async () => {
+  createDOM(
+    `<div class="foreman-empty-state"><div><div class="empty-state-description">Description</div><span id="sentence">See <a href="/links/manual">documentation</a></span></div><ul id="permissions"><li>view_hosts</li></ul><a id="create" href="/hosts/new">Create</a></div><ul><li id="docs"><button data-ouia-component-id="doc-url-dropdown">Docs</button></li><li id="support"><a href="/links/support">Support</a></li></ul>`
+  );
+  const doc = document;
+  hideDocumentation(doc);
+  assert(doc.querySelector('#docs button').classList.contains(hiddenClass));
+  assert(!doc.getElementById('docs').classList.contains(hiddenClass));
+  ['sentence', 'permissions', 'create', 'support'].forEach((id) => {
+    assert(!doc.getElementById(id).classList.contains(hiddenClass));
+  });
+  assert.equal(
+    doc.querySelector('#sentence a').getAttribute('href'),
+    '/links/manual'
+  );
+});
+
+test('handles React node reuse without leaving functional links hidden', async () => {
+  createDOM(
+    '<a data-ouia-component-id="audits-documentation-button" href="/links/manual">Documentation</a>'
+  );
+  const doc = document;
+  hideDocumentation(doc);
+  const link = doc.querySelector('a');
+  assert(link.classList.contains(hiddenClass));
+  link.setAttribute('data-ouia-component-id', 'create-host');
+  link.href = '/hosts/new';
+  hideDocumentation(doc);
+  assert(!link.classList.contains(hiddenClass));
+});
+
+test('observes late documentation buttons and reused control identifiers', async () => {
+  createDOM('<main></main>');
+  const doc = document;
+  const observer = installDocumentationHiding(doc);
+  const link = doc.createElement('a');
+  link.href = '/links/docs/Managing_Hosts';
+  link.setAttribute(
+    'data-ouia-component-id',
+    'register-host-documentation-button'
+  );
+  doc.body.appendChild(link);
+  await new Promise((resolve) => setTimeout(resolve, 60));
+  assert(link.classList.contains(hiddenClass));
+  link.setAttribute('data-ouia-component-id', 'create-host');
+  link.href = '/hosts/new';
+  await new Promise((resolve) => setTimeout(resolve, 60));
+  assert(!link.classList.contains(hiddenClass));
+  observer.disconnect();
+});
+
+test('hides localized table documentation without hiding other dropdown actions', async () => {
+  createDOM(
+    '<div data-ouia-component-id="action-buttons-dropdown"><ul><li id="docs"><a data-ouia-component-id="Dokumentace-dropdown-item" href="/hosts/help">Dokumentace</a></li><li id="export"><a data-ouia-component-id="Export-dropdown-item" href="/hosts.csv">Export</a></li></ul></div>'
+  );
+  hideDocumentation(document, 'Dokumentace');
+  assert(document.querySelector('#docs a').classList.contains(hiddenClass));
+  assert(!document.getElementById('export').classList.contains(hiddenClass));
+});
+
+test('welcome sentences keep their documentation links', async () => {
+  assert.doesNotMatch(styles, /a\[href/);
+  createDOM(`
+    <div class="pf-v5-c-empty-state__body">
+      <div class="empty-state-description">No discovered hosts found in this context.</div>
+      <span id="discovered">For more information please see <a href="/links/plugin_manual?name=foreman_discovery">documentation</a></span>
+    </div>
+    <div class="empty-state-description" id="reports">If you wish to configure Puppet to forward its reports to Foreman, please follow <a href="/links/manual/3.5.4PuppetReports">setting up reporting</a> and <a href="/links/wiki/Mail_Notifications">e-mail reporting</a></div>
+  `);
+  const doc = document;
+  hideDocumentation(doc, 'Documentation');
+  normalizeSatelliteDocumentation(doc, '/links/manual');
+  assert.equal(
+    doc.querySelector('#discovered').textContent,
+    'For more information please see documentation'
+  );
+  assert.equal(
+    doc.querySelector('#reports').textContent,
+    'If you wish to configure Puppet to forward its reports to Foreman, please follow setting up reporting and e-mail reporting'
+  );
+  doc.querySelectorAll('#discovered a, #reports a').forEach((link) => {
+    assert.notEqual(window.getComputedStyle(link).display, 'none');
+  });
+});
+
+test('CSS and JavaScript leave inline documentation links visible', async () => {
+  const urls = [
+    '/links/manual',
+    '/links/docs/Managing_Hosts',
+    '/links/plugin_manual',
+    '/links/wiki',
+    'https://docs.redhat.com/en/documentation',
+    'https://docs.theforeman.org/',
+  ];
+  createDOM(
+    urls.map((url) => `<p>See <a href="${url}">documentation</a>.</p>`).join('')
+  );
+  hideDocumentation(document);
+  document.querySelectorAll('a').forEach((link) => {
+    assert.notEqual(window.getComputedStyle(link).display, 'none');
+    assert.notEqual(
+      window.getComputedStyle(link.parentElement).display,
+      'none'
+    );
+  });
+});
+
+test('hides only the upgrade documentation button and preserves card content and helper', async () => {
+  createDOM(
+    '<section id="card"><p id="description">Upgrade instructions</p><a data-ouia-component-id="upgrade-docs-button" href="/links/upgrade?section=documentation">Documentation</a><a id="helper" data-ouia-component-id="upgrade-helper-button" href="/links/upgrade?section=helper">Upgrade helper</a></section>'
+  );
+  hideDocumentation(document);
+  const style = (selector) =>
+    window.getComputedStyle(document.querySelector(selector)).display;
+  assert.equal(style('[data-ouia-component-id="upgrade-docs-button"]'), 'none');
+  ['#card', '#description', '#helper'].forEach((selector) => {
+    assert.notEqual(style(selector), 'none');
+  });
+});
+
+test('direct Satellite links use the landing redirect while other products and support remain unchanged', async () => {
+  const satelliteUrls = [
+    'https://docs.redhat.com/en/documentation/red_hat_satellite/6.19/managing_hosts/index#chapter',
+    'https://access.redhat.com/documentation/en-us/red_hat_satellite/6.10/html/guide/chapter',
+    'https://offline.example/docs/en/documentation/red_hat_satellite/6.19/guide',
+  ];
+  const preserved = [
+    'https://docs.redhat.com/en/documentation/subscription_central/1/guide',
+    'https://docs.ansible.com/ansible/latest/guide',
+    'https://access.redhat.com/products/red-hat-satellite#get-support',
+    'https://access.redhat.com/labs/satelliteupgradehelper',
+    'https://access.redhat.com/solutions/satellite6-tasks#task',
+    'https://access.redhat.com/articles/1586183',
+  ];
+  createDOM(
+    [...satelliteUrls, ...preserved]
+      .map((url) => `<a href="${url}">Documentation</a>`)
+      .join('')
+  );
+  normalizeSatelliteDocumentation(document, '/prefix/links/manual');
+  const links = [...document.querySelectorAll('a')];
+  links.slice(0, satelliteUrls.length).forEach((link) => {
+    assert.equal(link.getAttribute('href'), '/prefix/links/manual');
+    assert.notEqual(window.getComputedStyle(link).display, 'none');
+  });
+  links
+    .slice(satelliteUrls.length)
+    .forEach((link, i) => assert.equal(link.href, preserved[i]));
+});
+
+test('normalizes late Satellite links and React href updates', async () => {
+  createDOM('<main></main>');
+  const observer = installDocumentationHiding(
+    document,
+    'Documentation',
+    '/prefix/links/manual'
+  );
+  const link = document.createElement('a');
+  link.href =
+    'https://docs.redhat.com/en/documentation/red_hat_satellite/6.19/guide';
+  document.body.appendChild(link);
+  await new Promise((resolve) => setTimeout(resolve, 60));
+  assert.equal(link.getAttribute('href'), '/prefix/links/manual');
+  link.href =
+    'https://docs.redhat.com/en/documentation/red_hat_satellite/6.19/another-guide';
+  await new Promise((resolve) => setTimeout(resolve, 60));
+  assert.equal(link.getAttribute('href'), '/prefix/links/manual');
+  observer.disconnect();
+});
+
+test('observer passes visit added subtrees and changed attributes only', async () => {
+  createDOM(
+    '<a id="outside" href="https://docs.ansible.com/ansible/latest/guide">Ansible</a><button id="kept" data-ouia-component-id="doc-url-dropdown">Docs</button><main></main>'
+  );
+  const doc = document;
+  const observer = installDocumentationHiding(
+    doc,
+    'Dokumentace',
+    '/prefix/links/manual'
+  );
+  const documentQueries = [];
+  const querySelectorAll = doc.querySelectorAll.bind(doc);
+  jest.spyOn(doc, 'querySelectorAll').mockImplementation((selector) => {
+    documentQueries.push(selector);
+    return querySelectorAll(selector);
+  });
+  const wrapper = doc.createElement('div');
+  wrapper.innerHTML =
+    '<div data-ouia-component-id="action-buttons-dropdown"><a id="localized" data-ouia-component-id="Dokumentace-dropdown-item" href="/hosts/help">Dokumentace</a></div><a id="inside" href="https://docs.redhat.com/en/documentation/red_hat_satellite/6.19/guide">Docs</a><button id="audits" data-ouia-component-id="audits-documentation-button">Documentation</button>';
+  doc.querySelector('main').appendChild(wrapper);
+  await new Promise((resolve) => setTimeout(resolve, 60));
+  assert.equal(documentQueries.length, 0);
+  assert.equal(
+    doc.getElementById('inside').getAttribute('href'),
+    '/prefix/links/manual'
+  );
+  assert.equal(
+    doc.getElementById('outside').getAttribute('href'),
+    'https://docs.ansible.com/ansible/latest/guide'
+  );
+  assert(doc.getElementById('localized').classList.contains(hiddenClass));
+  assert(doc.getElementById('audits').classList.contains(hiddenClass));
+  assert(doc.getElementById('kept').classList.contains(hiddenClass));
+  doc
+    .getElementById('localized')
+    .setAttribute('data-ouia-component-id', 'Export-dropdown-item');
+  await new Promise((resolve) => setTimeout(resolve, 60));
+  assert.equal(documentQueries.length, 0);
+  assert(!doc.getElementById('localized').classList.contains(hiddenClass));
+  assert(doc.getElementById('kept').classList.contains(hiddenClass));
+  assert(doc.getElementById('audits').classList.contains(hiddenClass));
+  observer.disconnect();
+});
+
+test('observer applies a mutation that arrives while a frame is scheduled', async () => {
+  createDOM('<main></main>');
+  const doc = document;
+  const observer = installDocumentationHiding(
+    doc,
+    'Documentation',
+    '/prefix/links/manual'
+  );
+  let frame = null;
+  jest.spyOn(window, 'requestAnimationFrame').mockImplementation((callback) => {
+    frame = callback;
+    return 1;
+  });
+  const link = doc.createElement('a');
+  link.href =
+    'https://docs.redhat.com/en/documentation/red_hat_satellite/6.19/guide';
+  doc.body.appendChild(link);
+  await Promise.resolve();
+  assert.equal(typeof frame, 'function');
+  const scheduledFrame = frame;
+  const button = doc.createElement('button');
+  button.setAttribute('data-ouia-component-id', 'audits-documentation-button');
+  doc.body.appendChild(button);
+  await Promise.resolve();
+  scheduledFrame();
+  assert.equal(link.getAttribute('href'), '/prefix/links/manual');
+  assert(button.classList.contains(hiddenClass));
+  observer.disconnect();
+});
+
+test('Reports inline sentence stays complete even beside a hidden documentation button', async () => {
+  createDOM(
+    '<ul><li id="report"><div class="empty-state-description">If you wish to configure Puppet to forward its reports to Foreman, please follow <a href="/links/manual/3.5.4PuppetReports">setting up reporting</a> and <a href="/links/wiki/Mail_Notifications">e-mail reporting</a></div><button data-ouia-component-id="audits-documentation-button">Documentation</button></li></ul>'
+  );
+  const doc = document;
+  hideDocumentation(doc);
+  normalizeSatelliteDocumentation(doc, '/links/manual');
+  assert.equal(
+    doc.querySelector('.empty-state-description').textContent,
+    'If you wish to configure Puppet to forward its reports to Foreman, please follow setting up reporting and e-mail reporting'
+  );
+  doc.querySelectorAll('.empty-state-description a').forEach((link) => {
+    for (let node = link; node; node = node.parentElement) {
+      assert.notEqual(window.getComputedStyle(node).display, 'none');
+    }
+  });
+  assert.equal(
+    window.getComputedStyle(doc.querySelector('button')).display,
+    'none'
+  );
+});

data/webpack/index.js

@@ -3,25 +3,56 @@ import React from 'react';
 import componentRegistry from 'foremanReact/components/componentRegistry';
 import { addGlobalFill } from 'foremanReact/components/common/Fill/GlobalFill';
 import { translate as __ } from 'foremanReact/common/I18n';
+import { foremanUrl } from 'foremanReact/common/helpers';
 import { Helmet } from 'react-helmet';
 
+import { installDocumentationHiding } from './documentation/hideDocumentation';
+
 import SatelliteUpgradeHelperCard from './components/fills/UpgradePage/SatelliteUpgradeHelperCard';
+import { SatelliteWelcomeEnv } from './components/SatelliteWelcomeEnv';
+
+const SATELLITE_FILL_WEIGHT = 1000;
 
 // register components for erb mounting
 componentRegistry.register({ name: 'Helmet', type: Helmet });
+componentRegistry.register({
+  name: 'SatelliteWelcomeEnv',
+  type: SatelliteWelcomeEnv,
+});
 
 addGlobalFill(
   'upgrade-page-upgrade-docs',
   'Satellite upgrade helper card',
   <SatelliteUpgradeHelperCard key="satellite-upgrade-helper-card" />,
-  1000,
+  SATELLITE_FILL_WEIGHT
 );
 addGlobalFill(
   'upgrade-page-footer',
   'Satellite upgrade page footer',
   {
-    helpDesc: __('If you require assistance or encounter issues, reach out to Red Hat Support or explore the resources available in the Customer Portal for troubleshooting.'),
+    helpDesc: __(
+      'If you require assistance or encounter issues, reach out to Red Hat Support or explore the resources available in the Customer Portal for troubleshooting.'
+    ),
     helpLinkText: __('Contact support'),
   },
-  1000,
+  SATELLITE_FILL_WEIGHT
 );
+
+if (document.readyState === 'loading') {
+  document.addEventListener(
+    'DOMContentLoaded',
+    () =>
+      installDocumentationHiding(
+        document,
+        __('Documentation'),
+        foremanUrl('/links/manual')
+      ),
+    { once: true }
+  );
+} else {
+  installDocumentationHiding(
+    document,
+    __('Documentation'),
+    foremanUrl('/links/manual')
+  );
+}

data/webpack/test_setup.js

@@ -0,0 +1,3 @@
+// Foreman's Jest configuration resolves this alias to its shared test setup.
+// eslint-disable-next-line import/no-unresolved
+import 'foremanJSTestSetup';

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foreman_theme_satellite
 version: !ruby/object:Gem::Version
-  version: 16.4.2
+  version: 16.4.3
 platform: ruby
 authors:
 - Shimon Stein
@@ -66,6 +66,7 @@ files:
 - app/assets/javascripts/foreman_theme_satellite/theme_ng_page_title.js
 - app/assets/stylesheets/foreman_theme_satellite/application_colors.css
 - app/assets/stylesheets/foreman_theme_satellite/bastion.scss
+- app/assets/stylesheets/foreman_theme_satellite/documentation.scss
 - app/assets/stylesheets/foreman_theme_satellite/external_logout.scss
 - app/assets/stylesheets/foreman_theme_satellite/foreman_theme_satellite.css
 - app/assets/stylesheets/foreman_theme_satellite/login.scss
@@ -76,6 +77,7 @@ files:
 - app/assets/stylesheets/foreman_theme_satellite/wizard.scss
 - app/controllers/concerns/documentation_controller_branding.rb
 - app/controllers/concerns/provisioning_templates_controller_branding.rb
+- app/helpers/documentation_visibility_helper.rb
 - app/helpers/provisioning_templates_helper_branding.rb
 - app/helpers/theme_application_helper.rb
 - app/helpers/theme_css_class_helper.rb
@@ -94,6 +96,7 @@ files:
 - app/models/concerns/setting_branding.rb
 - app/models/concerns/upstream_only_settings.rb
 - app/overrides/bootdisk_help_page.rb
+- app/overrides/hide_documentation.rb
 - app/overrides/layouts/base/eol_banner.html.erb.deface
 - app/overrides/layouts/base/theme_react_root.html.erb.deface
 - app/overrides/layouts/base/theme_resources.html.erb.deface
@@ -148,8 +151,14 @@ files:
 - locale/zh_CN/LC_MESSAGES/foreman_theme_satellite.mo
 - locale/zh_CN/foreman_theme_satellite.po
 - package.json
+- webpack/components/SatelliteWelcomeEnv.js
 - webpack/components/fills/UpgradePage/SatelliteUpgradeHelperCard.js
+- webpack/documentation/documentationMenuKeyboard.js
+- webpack/documentation/documentationMenuKeyboard.test.js
+- webpack/documentation/hideDocumentation.js
+- webpack/documentation/hideDocumentation.test.js
 - webpack/index.js
+- webpack/test_setup.js
 homepage: https://github.com/RedHatSatellite/foreman_theme_satellite
 licenses:
 - GPL-3.0