From 58c36b60912ade80f9a5fe59de9b9b8a1cb3a5bf Mon Sep 17 00:00:00 2001 From: Andrew Nicols Date: Mon, 8 Jun 2026 12:01:04 +0800 Subject: [PATCH 1/2] [repo] Add a new FileTree structure component Support creation of clear directory structures in a tree-like format using JSON notation: ``` ``` --- docs/guides/javascript/react/testing.md | 69 +++++++++++++------- src/components/FileTree/index.tsx | 87 +++++++++++++++++++++++++ 2 files changed, 131 insertions(+), 25 deletions(-) create mode 100644 src/components/FileTree/index.tsx diff --git a/docs/guides/javascript/react/testing.md b/docs/guides/javascript/react/testing.md index 302a79739..012f0333b 100644 --- a/docs/guides/javascript/react/testing.md +++ b/docs/guides/javascript/react/testing.md @@ -43,34 +43,53 @@ npm test -- --coverage Test files must match the glob `**/esm/tests/**/*.test.{ts,tsx}`. Place them alongside the source they test: -``` -public -└── lib - └── js - └── esm - ├── src - │ └── output - │ └── ExampleComponent.tsx - └── tests - └── output - └── ExampleComponent.test.ts -``` +import FileTree from '@site/src/components/FileTree'; + + The same convention applies to plugin components: -``` -public -└── mod - └── forum - └── js - └── esm - ├── src - │ └── output - │ └── ExampleComponent.tsx - └── tests - └── output - └── ExampleComponent.test.ts -``` + ## Writing a test diff --git a/src/components/FileTree/index.tsx b/src/components/FileTree/index.tsx new file mode 100644 index 000000000..4a240d774 --- /dev/null +++ b/src/components/FileTree/index.tsx @@ -0,0 +1,87 @@ +/** + * Copyright (c) Moodle Pty Ltd. + * + * Moodle is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * Moodle is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with Moodle. If not, see . + */ + +import React from 'react'; +import CodeBlock from '@theme/CodeBlock'; + +function parseObjectTree(tree: DirectoryStructure, prefix = ''): string { + const keys = Object.keys(tree); + let result = ''; + + keys.forEach((key, index) => { + const isLast = index === keys.length - 1; + const pointer = isLast ? '└── ' : '├── '; + const nextPrefix = prefix + (isLast ? ' ' : '│ '); + + const value = tree[key]; + + let comment = ''; + let children: DirectoryStructure | undefined; + + // Determine the format at runtime + if (value !== null && typeof value === 'object') { + if ('_comment' in value || '_children' in value) { + // It's using the expanded object format + const expanded = value as ExpandedItem; + comment = expanded._comment ? ` # ${expanded._comment}` : ''; // eslint-disable-line no-underscore-dangle + children = expanded._children; // eslint-disable-line no-underscore-dangle + } else { + // It's using the simple nested directory format + children = value as DirectoryStructure; + } + } else if (typeof value === 'string') { + // Inline shorthand string comment support: "filename": "comment string" + comment = ` # ${value}`; + } + + // 1. Append the node line + result += `${prefix}${pointer}${key}${comment}\n`; + + // 2. Recurse into children if they exist + if (children) { + result += parseObjectTree(children, nextPrefix); + } + }); + + return result; +} + +type FileValue = string | null; + +export interface ExpandedItem { + _comment?: string; + _children?: DirectoryStructure; +} + +// A node can now be a primitive file, a simple nested directory, or an expanded item +export type TreeItem = FileValue | DirectoryStructure | ExpandedItem; + +export interface DirectoryStructure { + [nodeName: string]: TreeItem; +} + +export type FileTreeProps = { + structure: DirectoryStructure; +}; + +export default function FileTree({ structure }: FileTreeProps): JSX.Element { + return ( + + {parseObjectTree(structure)} + + ); +} From 33a6e7d127ea2d1d897e8d1e37f934c2d59d3f75 Mon Sep 17 00:00:00 2001 From: Andrew Nicols Date: Sun, 7 Jun 2026 21:26:51 +0800 Subject: [PATCH 2/2] [docs] Document the theming of Components --- docs/guides/javascript/react/theming.md | 152 ++++++++++++++++++++++++ 1 file changed, 152 insertions(+) create mode 100644 docs/guides/javascript/react/theming.md diff --git a/docs/guides/javascript/react/theming.md b/docs/guides/javascript/react/theming.md new file mode 100644 index 000000000..f2ef85dab --- /dev/null +++ b/docs/guides/javascript/react/theming.md @@ -0,0 +1,152 @@ +--- +title: Theming Components +tags: + - react + - javascript + - theming + - theme +description: How to theme React Components +--- + + + +Moodle supports the theming of React components using dynamic path-resolution for React components based on the user's active theme. It allows theme developers to fully override React components for both Moodle core, and any Moodle plugin, while providing mechanisms to extend or fall back to original implementations. + +## How Path Resolution Works + +When a component is requested using the standard naming format (`@moodle/lms//`), the system dynamically checks the user's **current theme** before falling back to the standard location. + +### Resolution Logic + +If a user's current theme is set to **`boost`**, a request for `@moodle/lms/core/ExampleComponent` triggers the following lookup sequence: + +1. Check for a theme-specific override: + + ``` + public/theme/boost/js/esm/src/overrides/core/ExampleComponent.tsx + ``` + +2. Fall back to Core (if no theme overrides exist) + + ``` + public/lib/js/esm/src/ExampleComponent.tsx + ``` + +Similarly, if a user's current theme is set to **`classic`**, a request for `@moodle/lms/mod_assign/local/grader/GradingPanel` triggers the following lookup sequence: + +1. Check for a theme-specific override: + + ``` + public/theme/classic/js/esm/src/overrides/mod_assign/local/grader/GradingPanel.tsx + ``` + +2. Fall back to the plugin (if no theme overrides exist) + + ``` + public/mod_assign/js/esm/src/local/grader/GradingPanel.tsx + ``` + +:::danger[Theme parent fallbacks] + +It is worth noting that components **do not** fall back to a parent theme. + +A request for a component in a child theme **does not** check the parent theme automatically. + +::: + +### The Override File Structure + +To override a component, the file must be placed within the theme's override directory using the following structure: + +```text +public/theme//js/esm/src/overrides// +``` + +## Importing Original or Parent Components + +Theme developers often need to wrap or extend an existing component rather than rewriting it from scratch. To prevent infinite loop resolution errors, specific aliases are provided to target the core or a parent theme explicitly. + +### Targeting the Core/Original Component + +To pull in the un-themed, baseline version of a component, use the `theme-original` scope modifier: + +```typescript title="public/theme/boost/js/esm/src/overrides/core/ExampleComponent.ts" +import {ExampleComponent as OriginalComponent} from '@moodle/lms/theme-original/core/ExampleComponent'; + +export const ExampleComponent = (props) => { + // Add custom theme wrappers around the original core component + return ( +
+ +
+ ); +}; +``` + +### Targeting a Parent Theme Component + +If your theme inherits from a hierarchy of themes, you can choose which overrides to attempt to load. For example, in the given theme structure: + +import FileTree from '@site/src/components/FileTree'; + + + +You can explicitly fetch either: + +- a version for the `classic` theme using `@moodle/lms/theme-classic/mod_myfirstplugin/ExampleComponent`; or +- a version for the `boost` theme using `@moodle/lms/theme-boost/mod_myfirstplugin/ExampleComponent`; or +- the version shipped with the plugin using `@moodle/lms/theme-original/mod_myfirstplugin/ExampleComponent`. + +```typescript title="public/theme/retro/js/esm/src/overrides/mod_myfirstplugin/ExampleComponent.ts" +import {ExampleComponent as ClassicComponent} from '@moodle/lms/theme-classic/mod_myfirstplugin/ExampleComponent'; + +export const ExampleComponent = (props) => { + // Extend the classic theme's implementation + return ; +}; +``` + +## Loading components from an override + +When overriding a component you must be careful not to introduce circular dependencies by loading the themed version of the _same_ component. + +:::critical + +Never use the bare `@moodle/lms/` alias to load the wrapped code inside an override file to reference the component you are overriding. + +::: + +```typescript title="public/theme/retro/js/esm/src/overrdies/mod_myfirstplugin/ExampleComponent.ts" +// We must use the `theme-original` variant to load the original here: +import { + ExampleComponent as OriginalComponent, +} from '@moodle/lms/theme-original/mod_myfirstplugin/ExampleComponent'; + +// But for loading _other_ components, we can use the standard import: +import {UnrelatedComponent} from '@moodle/lms/mod_myfirstplugin/UnrelatedComponent'; + +export const ExampleComponent = (props) => { + return ( + + ; + + ); +}; + +``` + +## Testing theme overrides + +You can write tests for your theme-specific overrides in the same way that tests can be written for other components. + +When importing your component under test, you must use the `theme-` import, for example: + +```typescript title="public/theme/boost/js/esm/tests/overrides/core/ExampleComponent.test.ts" +import {ExampleComponent} from '@moodle/lms/theme-boost/core/ExampleComponent'; +```