From 117004e3f5ac3a1718214624bdb6a46ed6058ac0 Mon Sep 17 00:00:00 2001
From: Jannik Stehle <j.stehle@opencloud.eu>
Date: Wed, 3 Dec 2025 13:57:55 +0100
Subject: [PATCH 1/2] feat: render readme.md file at the top of folder

Renders the readme.md file at to the top each folder if present.
---
 .../src/components/FilesList/ListHeader.vue   | 106 ++++++++++++++++++
 .../src/views/spaces/GenericSpace.vue         |  19 +++-
 .../src/components/TextEditor/TextEditor.vue  |  38 ++++---
 3 files changed, 145 insertions(+), 18 deletions(-)
 create mode 100644 packages/web-app-files/src/components/FilesList/ListHeader.vue

diff --git a/packages/web-app-files/src/components/FilesList/ListHeader.vue b/packages/web-app-files/src/components/FilesList/ListHeader.vue
new file mode 100644
index 0000000000..c521c84614
--- /dev/null
+++ b/packages/web-app-files/src/components/FilesList/ListHeader.vue
@@ -0,0 +1,106 @@
+<template>
+  <div>
+    <div
+      v-if="loadReadmeContentTask.isRunning || !loadReadmeContentTask.last"
+      class="flex justify-center"
+    >
+      <oc-spinner size="large" class="my-4" :aria-label="$gettext('Loading README content')" />
+    </div>
+    <div
+      v-else
+      ref="markdownContainerRef"
+      class="markdown-container flex min-h-0 [&.collapsed]:max-h-[300px] [&.collapsed]:overflow-hidden"
+      :class="{
+        collapsed: markdownCollapsed,
+        'mask-linear-[180deg,black,80%,transparent]': markdownCollapsed && showMarkdownCollapse
+      }"
+    >
+      <text-editor class="w-full" is-read-only :current-content="markdownContent" />
+    </div>
+    <div v-if="showMarkdownCollapse && markdownContent" class="markdown-collapse text-center mt-2">
+      <oc-button appearance="raw" no-hover @click="toggleMarkdownCollapsed">
+        <span>{{ toggleMarkdownCollapsedText }}</span>
+      </oc-button>
+    </div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, unref, useTemplateRef } from 'vue'
+import { Resource, SpaceResource } from '@opencloud-eu/web-client'
+import { TextEditor, useClientService } from '@opencloud-eu/web-pkg'
+import { useTask } from 'vue-concurrency'
+import { useGettext } from 'vue3-gettext'
+
+const { space, readmeFile } = defineProps<{
+  space: SpaceResource
+  readmeFile: Resource
+}>()
+
+const { $gettext } = useGettext()
+const clientService = useClientService()
+const { getFileContents } = clientService.webdav
+
+const markdownContainerRef = useTemplateRef('markdownContainerRef')
+const markdownContent = ref('')
+const markdownCollapsed = ref(true)
+const showMarkdownCollapse = ref(false)
+
+const toggleMarkdownCollapsedText = computed(() => {
+  return unref(markdownCollapsed) ? $gettext('Show more') : $gettext('Show less')
+})
+const toggleMarkdownCollapsed = () => {
+  markdownCollapsed.value = !unref(markdownCollapsed)
+}
+
+const onMarkdownResize = () => {
+  if (!unref(markdownContainerRef)) {
+    return
+  }
+
+  unref(markdownContainerRef).classList.remove('collapsed')
+  const markdownContainerHeight = unref(markdownContainerRef).offsetHeight
+  if (markdownContainerHeight < 300) {
+    showMarkdownCollapse.value = false
+    return
+  }
+  showMarkdownCollapse.value = true
+
+  if (unref(markdownCollapsed)) {
+    unref(markdownContainerRef).classList.add('collapsed')
+  }
+}
+const markdownResizeObserver = new ResizeObserver(onMarkdownResize)
+const observeMarkdownContainerResize = () => {
+  if (!markdownResizeObserver || !unref(markdownContainerRef)) {
+    return
+  }
+  markdownResizeObserver.unobserve(unref(markdownContainerRef))
+  markdownResizeObserver.observe(unref(markdownContainerRef))
+}
+const unobserveMarkdownContainerResize = () => {
+  if (!markdownResizeObserver || !unref(markdownContainerRef)) {
+    return
+  }
+  markdownResizeObserver.unobserve(unref(markdownContainerRef))
+}
+
+const loadReadmeContentTask = useTask(function* (signal) {
+  try {
+    const { body } = yield getFileContents(space, { fileId: unref(readmeFile).id }, { signal })
+    markdownContent.value = body || ''
+  } catch (e) {
+    console.error('failed to load README.md content', e)
+  }
+})
+
+onMounted(async () => {
+  await loadReadmeContentTask.perform()
+  await nextTick()
+  observeMarkdownContainerResize()
+})
+
+onBeforeUnmount(() => {
+  unobserveMarkdownContainerResize()
+})
+</script>
diff --git a/packages/web-app-files/src/views/spaces/GenericSpace.vue b/packages/web-app-files/src/views/spaces/GenericSpace.vue
index 09f5298953..50d0bf9de8 100644
--- a/packages/web-app-files/src/views/spaces/GenericSpace.vue
+++ b/packages/web-app-files/src/views/spaces/GenericSpace.vue
@@ -52,6 +52,12 @@
             </template>
           </no-content-message>
           <template v-else>
+            <list-header
+              v-if="readmeFile && !hasSpaceHeader"
+              :space="space"
+              :readme-file="readmeFile"
+              class="mx-4 my-2"
+            />
             <resource-details
               v-if="displayResourceAsSingleResource"
               :single-resource="paginatedResources[0]"
@@ -182,6 +188,7 @@ import {
 } from '../../composables/keyboardActions'
 import { storeToRefs } from 'pinia'
 import { folderViewsFolderExtensionPoint } from '../../extensionPoints'
+import ListHeader from '../../components/FilesList/ListHeader.vue'
 
 export default defineComponent({
   name: 'GenericSpace',
@@ -202,7 +209,8 @@ export default defineComponent({
     ResourceTable,
     ResourceTiles,
     SpaceHeader,
-    WhitespaceContextMenu
+    WhitespaceContextMenu,
+    ListHeader
   },
   props: {
     space: {
@@ -460,6 +468,12 @@ export default defineComponent({
       }
     }
 
+    const readmeFile = computed(() => {
+      return unref(resourcesViewDefaults.storeItems).find(
+        (item) => item.name.toLowerCase() === 'readme.md'
+      )
+    })
+
     onMounted(() => {
       performLoaderTask(false)
       loadResourcesEventToken = eventBus.subscribe(
@@ -570,7 +584,8 @@ export default defineComponent({
       totalResourcesCount,
       areHiddenFilesShown,
       fileDropped,
-      loadPreview
+      loadPreview,
+      readmeFile
     }
   },
 
diff --git a/packages/web-pkg/src/components/TextEditor/TextEditor.vue b/packages/web-pkg/src/components/TextEditor/TextEditor.vue
index 79d667a37f..1d8eef4930 100644
--- a/packages/web-pkg/src/components/TextEditor/TextEditor.vue
+++ b/packages/web-pkg/src/components/TextEditor/TextEditor.vue
@@ -3,21 +3,22 @@
     id="text-editor-container"
     class="h-full [&_.md-editor-preview]:!font-(family-name:--oc-font-family)"
   >
-    <md-preview
-      v-if="isReadOnly"
-      id="text-editor-preview-component"
-      :model-value="currentContent"
-      no-katex
-      no-mermaid
-      no-prettier
-      no-upload-img
-      no-highlight
-      no-echarts
-      :language="languages[language.current] || 'en-US'"
-      :theme="theme"
-      auto-focus
-      read-only
-    />
+    <article v-if="isReadOnly">
+      <md-preview
+        id="text-editor-preview-component"
+        :model-value="currentContent"
+        no-katex
+        no-mermaid
+        no-prettier
+        no-upload-img
+        no-highlight
+        no-echarts
+        :language="languages[language.current] || 'en-US'"
+        :theme="theme"
+        auto-focus
+        read-only
+      />
+    </article>
     <md-editor
       v-else
       id="text-editor-component"
@@ -43,7 +44,7 @@
           @on-click="showLineNumbers = !showLineNumbers"
         >
           <oc-icon
-            class="!flex items-center justify-center w-[24px] h-[24px]"
+            class="!flex items-center justify-center size-6"
             size="small"
             name="hashtag"
             fill-type="none"
@@ -264,6 +265,11 @@ export default defineComponent({
   background-color: transparent;
 }
 
+#text-editor-component-preview > :first-child,
+#text-editor-preview-component-preview > :first-child {
+  margin-top: 0 !important;
+}
+
 // overwrite md-editor styles
 .md-editor {
   height: 100%;

From 9f67ef7788a1335171bab33868c9b9ff6a9c8237 Mon Sep 17 00:00:00 2001
From: Jannik Stehle <j.stehle@opencloud.eu>
Date: Fri, 5 Dec 2025 14:24:16 +0100
Subject: [PATCH 2/2] test: add unit tests for list header

---
 .../components/FilesList/ListHeader.spec.ts   | 39 +++++++++++++++++++
 .../unit/views/spaces/GenericSpace.spec.ts    | 36 ++++++++++++++---
 2 files changed, 69 insertions(+), 6 deletions(-)
 create mode 100644 packages/web-app-files/tests/unit/components/FilesList/ListHeader.spec.ts

diff --git a/packages/web-app-files/tests/unit/components/FilesList/ListHeader.spec.ts b/packages/web-app-files/tests/unit/components/FilesList/ListHeader.spec.ts
new file mode 100644
index 0000000000..ac4920325c
--- /dev/null
+++ b/packages/web-app-files/tests/unit/components/FilesList/ListHeader.spec.ts
@@ -0,0 +1,39 @@
+import ListHeader from '../../../../src/components/FilesList/ListHeader.vue'
+import { defaultComponentMocks, defaultPlugins, shallowMount } from '@opencloud-eu/web-test-helpers'
+import { mock } from 'vitest-mock-extended'
+import { Resource, SpaceResource } from '@opencloud-eu/web-client'
+import { flushPromises } from '@vue/test-utils'
+
+describe('ListHeader', () => {
+  it('renders a spinner when loading', () => {
+    const wrapper = getWrapper()
+    expect(wrapper.find('oc-spinner-stub').exists()).toBeTruthy()
+  })
+  it('renders a markdown container when README content is loaded', async () => {
+    const wrapper = getWrapper()
+    await flushPromises()
+    expect(wrapper.find('.markdown-container').exists()).toBeTruthy()
+  })
+})
+
+function getWrapper() {
+  const mocks = {
+    ...defaultComponentMocks()
+  }
+
+  mocks.$clientService.webdav.getFileContents.mockResolvedValueOnce({
+    body: 'Sample README content'
+  })
+
+  return shallowMount(ListHeader, {
+    props: {
+      space: mock<SpaceResource>(),
+      readmeFile: mock<Resource>()
+    },
+    global: {
+      mocks,
+      plugins: [...defaultPlugins()],
+      provide: mocks
+    }
+  })
+}
diff --git a/packages/web-app-files/tests/unit/views/spaces/GenericSpace.spec.ts b/packages/web-app-files/tests/unit/views/spaces/GenericSpace.spec.ts
index f967dbfcba..55dc281fd9 100644
--- a/packages/web-app-files/tests/unit/views/spaces/GenericSpace.spec.ts
+++ b/packages/web-app-files/tests/unit/views/spaces/GenericSpace.spec.ts
@@ -81,7 +81,7 @@ describe('GenericSpace view', () => {
       expect(wrapper.find('.no-content-message').exists()).toBeTruthy()
     })
     it('shows the files table when files are available', () => {
-      const { wrapper } = getMountedWrapper({ files: [mock<Resource>()] })
+      const { wrapper } = getMountedWrapper({ files: [mock<Resource>({ name: 'file.txt' })] })
       expect(wrapper.find('.no-content-message').exists()).toBeFalsy()
       expect(wrapper.find('resource-table-stub').exists()).toBeTruthy()
     })
@@ -175,7 +175,7 @@ describe('GenericSpace view', () => {
       it('renders the ResourceDetails component if no currentFolder id is present', () => {
         const { wrapper } = getMountedWrapper({
           currentFolder: mock<Resource>({ fileId: '' }),
-          files: [mock<Resource>({ isFolder: false })],
+          files: [mock<Resource>({ name: 'file.txt', isFolder: false })],
           runningOnEos: true
         })
         expect(wrapper.find('resource-details-stub').exists()).toBeTruthy()
@@ -187,7 +187,7 @@ describe('GenericSpace view', () => {
             ...mock<Resource>(),
             path
           },
-          files: [{ ...mock<Resource>(), path }],
+          files: [{ ...mock<Resource>({ name: 'file.txt' }), path }],
           runningOnEos: true
         })
         expect(wrapper.find('resource-details-stub').exists()).toBeTruthy()
@@ -199,7 +199,7 @@ describe('GenericSpace view', () => {
           currentFolder: {
             ...mock<Resource>()
           },
-          files: [{ ...mock<Resource>(), isFolder: false }],
+          files: [{ ...mock<Resource>({ name: 'file.txt' }), isFolder: false }],
           space: mock<SpaceResource>({
             id: '1',
             getDriveAliasAndItem: vi.fn(),
@@ -230,6 +230,23 @@ describe('GenericSpace view', () => {
       expect(wrapper.find(selectors.actionsCreateAndUpload).exists()).toBe(true)
     })
   })
+  describe('list header', () => {
+    it('renders when a readme file is present', () => {
+      const { wrapper } = getMountedWrapper({ files: [mock<Resource>({ name: 'readme.md' })] })
+      expect(wrapper.find('list-header-stub').exists()).toBeTruthy()
+    })
+    it('does not render when a readme file is not present', () => {
+      const { wrapper } = getMountedWrapper({ files: [mock<Resource>({ name: 'file.txt' })] })
+      expect(wrapper.find('list-header-stub').exists()).toBeFalsy()
+    })
+    it('does not render on the frontpage of a space', () => {
+      const { wrapper } = getMountedWrapper({
+        files: [mock<Resource>({ name: 'readme.md' })],
+        space: mock<SpaceResource>({ driveType: 'project' })
+      })
+      expect(wrapper.find('list-header-stub').exists()).toBeFalsy()
+    })
+  })
 })
 
 function getMountedWrapper({
@@ -269,7 +286,8 @@ function getMountedWrapper({
 
   const resourcesViewDetailsMock = useResourcesViewDefaultsMock({
     paginatedResources: ref(files),
-    areResourcesLoading: ref(loading)
+    areResourcesLoading: ref(loading),
+    storeItems: ref(files)
   })
   vi.mocked(useResourcesViewDefaults).mockImplementation(() => resourcesViewDetailsMock)
   vi.mocked(useBreadcrumbsFromPath).mockImplementation(() =>
@@ -296,7 +314,13 @@ function getMountedWrapper({
         plugins,
         mocks: defaultMocks,
         provide: defaultMocks,
-        stubs: { ...defaultStubs, 'resource-details': true, portal: true, ...stubs }
+        stubs: {
+          ...defaultStubs,
+          'resource-details': true,
+          portal: true,
+          ...stubs,
+          ListHeader: true
+        }
       }
     })
   }