feat: use features for dynamic shell header/footer visibility

Apps can now hide the shell header or footer on specific routes
by declaring role strings under hideHeaderFeatureId or
hideFooterFeatureId in their features config. The shell checks
these against active roles at render time.

BREAKING CHANGE: App.provides is now App.features. getProvidedData()
is now getFeatureData(). getProvidesAsRoles() is replaced by
getFeatureDataAsStrings() and moved from the shell into the
runtime. All identifier constants use the FeatureId suffix and
the frontend.feature.* namespace. The ADR has been renamed to
0013-app-features-for-inter-app-configuration.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: arbrandes

…0013-app-provides-for-inter-app-data.rst …features-for-inter-app-configuration.rstdocs/decisions/0013-app-provides-for-inter-app-data.rst renamed to docs/decisions/0013-app-features-for-inter-app-configuration.rst docs/decisions/0013-app-provides-for-inter-app-data.rst renamed to docs/decisions/0013-app-features-for-inter-app-configuration.rst

@@ -1,5 +1,5 @@
-App ``provides`` for Inter-App Data
-####################################
+App ``features`` for Inter-App Configuration
+############################################
 
 Status
 ======
@@ -11,15 +11,15 @@ Context
 =======
 
 frontend-base applications currently communicate through two structured
-mechanisms: ``routes`` and ``slots``.  Both are defined in the ``App`` interface
-and consumed directly by frontend-base's runtime.
+mechanisms: ``routes``, ``slots``, and ``providers``.  All are defined in the
+``App`` interface and consumed directly by frontend-base's runtime.
 
-As the platform evolves, however, situations arise where apps need to share data
-with each other that frontend-base itself has no reason to understand.  A
-concrete example is the course navigation bar introduced in the header app.
-The header needs to know two things from other apps:
+As the platform evolves, however, situations arise where apps need to share
+configuration data with each other that frontend-base itself has no reason to
+understand.  A concrete example is the course navigation bar introduced in the
+header app. The header needs to know two things from other apps:
 
-1. Which apps want the course navigation bar to appear (currently a hardcoded
+1. Which apps want the course navigation bar to appear (previously a hardcoded
    list of roles in ``constants.ts``).
 
 2. Which URL patterns each app handles client-side, so the navigation bar can
@@ -36,14 +36,14 @@ runtime needs to interpret them directly.  It builds a router from ``routes``
 and renders widgets from ``slots``.  Any new field that frontend-base itself
 must consume deserves the same treatment: a dedicated, typed field.
 
-But for data that flows between apps - where frontend-base is just the conduit -
-a generic mechanism is more appropriate.
+But for generic configuration between apps - where frontend-base is just the
+conduit - a generic mechanism is more appropriate.
 
 
 Decision
 ========
 
-Add an optional ``provides`` field to the ``App`` interface::
+Add an optional ``features`` field to the ``App`` interface::
 
     export interface App {
       appId: string,
@@ -52,40 +52,39 @@ Add an optional ``provides`` field to the ``App`` interface::
       providers?: AppProvider[],
       slots?: SlotOperation[],
       config?: AppConfig,
-      provides?: Record<string, unknown>,
+      features?: Record<string, unknown>,
     }
 
-``provides`` is a flat key-value map where each key is an identifier agreed
-upon by the providing and consuming apps, and the value is whatever the
-consumer expects.  frontend-base stores this data and exposes it through a
-runtime function, but does not interpret it.  Any namespaced identifier can
-serve as a key.
+``features`` is a flat key-value map where each key is a feature identifier
+agreed upon by the providing and consuming apps, and the value takes whatever
+shape the app that provides the feature expects.  The runtime stores this data
+and exposes it through a runtime function, but does not interpret it.  Any
+namespaced identifier can serve as a key.
 
 A runtime helper would look something like::
 
-    // Returns all `provides` entries matching the given key.
-    function getProvidedData(key: string): unknown[]
+    // Returns all `features` entries matching the given feature identifier.
+    function getFeatureData(id: string): unknown[]
 
 
 Guidelines
 ==========
 
-1. ``provides`` is for inter-app data that frontend-base does not need to
-   interpret.  If frontend-base's runtime must consume the data to function
-   (as it does with routes and slots), a dedicated typed field on ``App`` is
-   the right choice.
+1. ``features`` is for inter-app configuration that the runtime does not need
+   to interpret.  If it must consume the data to function (as it does with
+   routes and slots), a dedicated typed field on ``App`` is the right choice.
 
-2. Keys in ``provides`` should be their own namespaced identifiers, not
+2. Keys in ``features`` should be their own namespaced feature identifiers, not
    duplicates of existing app, slot, or widget IDs.  This allows different
-   widgets or other entities to consume the same provided data independently,
+   widgets or other entities to consume the same feature data independently,
    without coupling the data's identity to a single consumer.
 
 3. The shape of the value under each key is a contract between the providing and
    consuming apps.  It is not enforced by frontend-base.  Consuming apps should
    validate or type-guard the data they receive.
 
-4. ``provides`` should not be used as a back door to modify frontend-base's
-   behavior.  It is not a configuration mechanism for the runtime.
+4. ``features`` should not be used as a back door to modify the runtime's
+   behavior.  It is not a configuration mechanism for the runtime itself.
 
 
 Consequences
@@ -96,7 +95,7 @@ frontend-base's ``App`` type or runtime for each new use case.  The ``App``
 interface grows by one optional field and remains stable as new inter-app
 patterns emerge.
 
-The trade-off is that ``provides`` data is untyped from frontend-base's
+The trade-off is that ``features`` data is untyped from frontend-base's
 perspective.  Consuming apps bear the responsibility of defining, documenting,
 and validating the shape of the data they expect.  This is acceptable because
 the data is, by definition, outside frontend-base's domain.
@@ -108,27 +107,28 @@ As a concrete illustration, the Instructor Dashboard app could declare::
 
     const config: App = {
       appId: 'org.openedx.frontend.app.instructor',
-      provides: {
-        'org.openedx.frontend.provides.courseNavigationRoles.v1': {
-          courseNavigationRoles: ['org.openedx.frontend.role.instructor'],
-        },
+      features: {
+        'org.openedx.frontend.feature.showCourseNavigationBar.v1': [
+          'org.openedx.frontend.role.instructor',
+        ],
       },
       routes: [...],
       slots: [...],
     };
 
-The header's course navigation bar widget collects ``provides`` entries keyed
-to its provides identifier from all registered apps.  From the provided roles
-it determines both when to render the navigation bar (by checking
-``getActiveRoles()``) and which tab URLs can be navigated client-side (by
-resolving roles to route paths via ``getUrlByRouteRole()``).
+The header's course navigation bar widget collects ``features`` entries keyed
+to its feature identifier from all registered apps.  It expects the provided
+values to be role identifiers, from which it determines both when to render the
+navigation bar (by checking ``getActiveRoles()``) and which tab URLs can be
+navigated client-side (by resolving roles to route paths via
+``getUrlByRouteRole()``).
 
 
 Rejected alternatives
 =====================
 
-Slot operations
----------------
+Widget operations
+-----------------
 
 Each app could register its own widget into the course navigation bar slot
 with an ``active`` condition on its role.  The ``OPTIONS`` operation can even
@@ -155,5 +155,17 @@ static data.  Each app would need a context, a provider component, and a
 consumer hook, and the header would need to aggregate across multiple contexts
 with no standard way to discover them.  Providers are the right tool when data
 changes over time and consumers need to re-render.  The course navigation roles
-are fixed at registration time and never change, making ``provides`` a more
+are fixed at registration time and never change, making ``features`` a more
 natural fit.
+
+Reusing ``App.config``
+----------------------
+
+The existing ``App.config`` field has the same type (``Record<string, unknown>``)
+and could theoretically hold feature data.  However, ``config`` is per-app: it
+is retrieved by ``appId`` via ``getAppConfig()`` and is meant to hold settings
+*for* that app.  ``features`` has a cross-app access pattern:
+``getFeatureData()`` collects entries from all apps that declared data under a
+given feature identifier.  Merging the two would require scanning every app's
+config for a specific key, blurring the distinction between settings an app
+consumes and data it exposes for others.

runtime/config/index.test.ts

@@ -3,7 +3,7 @@ import * as subscriptions from '../subscriptions';
 import {
   addAppConfigs,
   getAppConfig,
-  getProvidedData,
+  getFeatureData,
   getSiteConfig,
   mergeSiteConfig,
   setSiteConfig,
@@ -352,10 +352,10 @@ describe('mergeSiteConfig', () => {
     });
   });
 
-  describe('getProvidedData', () => {
+  describe('getFeatureData', () => {
     it('should return empty array when no apps exist', () => {
       setSiteConfig({ ...defaultSiteConfig, apps: [] });
-      expect(getProvidedData('org.openedx.frontend.provides.testKey.v1')).toEqual([]);
+      expect(getFeatureData('org.openedx.frontend.feature.testFeatureId.v1')).toEqual([]);
     });
 
     it('should return empty array when no apps provide data for the consumer', () => {
@@ -366,7 +366,7 @@ describe('mergeSiteConfig', () => {
           { appId: 'app-two' },
         ],
       });
-      expect(getProvidedData('org.openedx.frontend.provides.testKey.v1')).toEqual([]);
+      expect(getFeatureData('org.openedx.frontend.feature.testFeatureId.v1')).toEqual([]);
     });
 
     it('should collect provided data from apps that declare it', () => {
@@ -375,20 +375,20 @@ describe('mergeSiteConfig', () => {
         apps: [
           {
             appId: 'app-one',
-            provides: {
-              'org.openedx.frontend.provides.testKey.v1': { urlPattern: '/one/' },
+            features: {
+              'org.openedx.frontend.feature.testFeatureId.v1': { urlPattern: '/one/' },
             },
           },
           {
             appId: 'app-two',
-            provides: {
-              'org.openedx.frontend.provides.testKey.v1': { urlPattern: '/two/' },
+            features: {
+              'org.openedx.frontend.feature.testFeatureId.v1': { urlPattern: '/two/' },
             },
           },
         ],
       });
 
-      const result = getProvidedData('org.openedx.frontend.provides.testKey.v1');
+      const result = getFeatureData('org.openedx.frontend.feature.testFeatureId.v1');
       expect(result).toEqual([
         { urlPattern: '/one/' },
         { urlPattern: '/two/' },
@@ -401,37 +401,37 @@ describe('mergeSiteConfig', () => {
         apps: [
           {
             appId: 'app-one',
-            provides: {
-              'org.openedx.frontend.provides.testKey.v1': { urlPattern: '/one/' },
-              'org.openedx.frontend.provides.otherKey.v1': { showBranding: true },
+            features: {
+              'org.openedx.frontend.feature.testFeatureId.v1': { urlPattern: '/one/' },
+              'org.openedx.frontend.feature.otherFeatureId.v1': { showBranding: true },
             },
           },
         ],
       });
 
-      const headerData = getProvidedData('org.openedx.frontend.provides.testKey.v1');
+      const headerData = getFeatureData('org.openedx.frontend.feature.testFeatureId.v1');
       expect(headerData).toEqual([{ urlPattern: '/one/' }]);
 
-      const footerData = getProvidedData('org.openedx.frontend.provides.otherKey.v1');
+      const footerData = getFeatureData('org.openedx.frontend.feature.otherFeatureId.v1');
       expect(footerData).toEqual([{ showBranding: true }]);
     });
 
-    it('should skip apps without provides', () => {
+    it('should skip apps without features', () => {
       setSiteConfig({
         ...defaultSiteConfig,
         apps: [
           { appId: 'app-one' },
           {
             appId: 'app-two',
-            provides: {
-              'org.openedx.frontend.provides.testKey.v1': { urlPattern: '/two/' },
+            features: {
+              'org.openedx.frontend.feature.testFeatureId.v1': { urlPattern: '/two/' },
             },
           },
           { appId: 'app-three', config: { VALUE: 'test' } },
         ],
       });
 
-      const result = getProvidedData('org.openedx.frontend.provides.testKey.v1');
+      const result = getFeatureData('org.openedx.frontend.feature.testFeatureId.v1');
       expect(result).toEqual([{ urlPattern: '/two/' }]);
     });
   });

runtime/config/index.ts

@@ -325,25 +325,39 @@ export function getActiveRoles() {
 }
 
 /**
- * Collects all `provides` entries from registered apps that match the given key.
+ * Collects all `features` entries from registered apps that match the given feature identifier.
  * This enables inter-app data sharing without frontend-base needing to understand the data shape.
  *
- * @param key - The namespaced identifier for the provided data.
- * @returns An array of provided data objects from all apps that declared data for this key.
+ * @param id - The namespaced feature identifier.
+ * @returns An array of feature data from all apps that declared data for this identifier.
  */
-export function getProvidedData(key: string): unknown[] {
+export function getFeatureData(id: string): unknown[] {
   const { apps } = getSiteConfig();
   if (!apps) return [];
 
   const results: unknown[] = [];
   for (const app of apps) {
-    if (app.provides && app.provides[key] !== undefined) {
-      results.push(app.provides[key]);
+    if (app.features && app.features[id] !== undefined) {
+      results.push(app.features[id]);
     }
   }
   return results;
 }
 
+/**
+ * Collects and flattens all `features` entries for the given feature identifier
+ * as strings.  Each entry can be a single string or a string array; entries
+ * of other types are silently skipped.
+ *
+ * @param id - The namespaced feature identifier.
+ * @returns A flat array of strings from all apps that declared data for this identifier.
+ */
+export function getFeatureDataAsStrings(id: string): string[] {
+  return getFeatureData(id)
+    .filter((data): data is string | string[] => typeof data === 'string' || Array.isArray(data))
+    .flat();
+}
+
 /**
  * Get an external link URL based on the URL provided. If the passed in URL is overridden in the
  * `externalLinkUrlOverrides` object, it will return the overridden URL. Otherwise, it will return

runtime/index.ts

@@ -45,7 +45,8 @@ export {
   getActiveWidgetRoles,
   getActiveRoles,
   getExternalLinkUrl,
-  getProvidedData
+  getFeatureData,
+  getFeatureDataAsStrings
 } from './config';
 
 export * from './constants';

shell/app.ts

@@ -1,15 +1,23 @@
-import { WidgetOperationTypes } from '../runtime';
+import { getActiveRoles, getFeatureDataAsStrings, WidgetOperationTypes } from '../runtime';
 import { App } from '../types';
 import { Footer } from './footer';
 import { Header } from './header';
+import { hideFooterFeatureId, hideHeaderFeatureId } from './constants';
 
-const inactive = [
-  'org.openedx.frontend.role.login',
-  'org.openedx.frontend.role.register',
-  'org.openedx.frontend.role.resetPassword',
-  'org.openedx.frontend.role.confirmPassword',
-  'org.openedx.frontend.role.welcome'
-];
+/*
+ * Checks whether a widget should render by comparing active roles against
+ * roles declared under the given feature.  Apps opt into hiding a widget by
+ * listing role strings in their `features` entry, e.g.:
+ *
+ *   features: { [hideHeaderFeatureId]: ['org.openedx.frontend.role.authn'] }
+ *
+ * The widget is disabled when any of those roles is currently active.
+ */
+function isWidgetEnabled(featureId: string): boolean {
+  const activeRoles = getActiveRoles();
+  const hideRoles = getFeatureDataAsStrings(featureId);
+  return !hideRoles.some(role => activeRoles.includes(role));
+}
 
 const app: App = {
   appId: 'org.openedx.frontend.app.shell',
@@ -20,7 +28,7 @@ const app: App = {
       op: WidgetOperationTypes.APPEND,
       component: Header,
       condition: {
-        inactive,
+        callback: () => isWidgetEnabled(hideHeaderFeatureId),
       }
     },
     {
@@ -29,7 +37,7 @@ const app: App = {
       op: WidgetOperationTypes.APPEND,
       component: Footer,
       condition: {
-        inactive,
+        callback: () => isWidgetEnabled(hideFooterFeatureId),
       }
     },
   ]

shell/constants.ts

@@ -0,0 +1,2 @@
+export const hideHeaderFeatureId = 'org.openedx.frontend.feature.hideHeader.v1';
+export const hideFooterFeatureId = 'org.openedx.frontend.feature.hideFooter.v1';