diff --git a/.eslintrc.json b/.eslintrc.json
index 80311ca60f..425974a61f 100644
--- a/.eslintrc.json
+++ b/.eslintrc.json
@@ -1,41 +1,44 @@
{
- "globals": {
- "EMOJIS": true,
- "PRODUCTION": true,
- "SCOPE_VERSION": true,
- "TRANSLATIONS": true,
- "oc_userconfig": true,
- "appName": true,
- "appVersion": true
- },
- "extends": [
- "@nextcloud/eslint-config/vue3"
- ],
- "parserOptions": {
- "babelOptions": {
- "plugins": [
- "@babel/plugin-syntax-import-assertions"
- ]
- }
- },
- "rules": {
- "@nextcloud/no-deprecations": [
- "error",
- {
- "parseAppInfo": false
- }
- ],
- "@nextcloud/no-removed-apis": [
- "error",
- {
- "parseAppInfo": false
- }
- ],
- "import/no-unresolved": [
- "error",
- {
- "ignore": ["\\?raw$"]
- }
- ]
- }
+ "globals": {
+ "EMOJIS": true,
+ "PRODUCTION": true,
+ "SCOPE_VERSION": true,
+ "TRANSLATIONS": true,
+ "oc_userconfig": true,
+ "appName": true,
+ "appVersion": true
+ },
+ "extends": [
+ "@nextcloud/eslint-config/vue3",
+ "plugin:storybook/recommended"
+ ],
+ "parserOptions": {
+ "babelOptions": {
+ "plugins": [
+ "@babel/plugin-syntax-import-assertions"
+ ]
+ }
+ },
+ "rules": {
+ "@nextcloud/no-deprecations": [
+ "error",
+ {
+ "parseAppInfo": false
+ }
+ ],
+ "@nextcloud/no-removed-apis": [
+ "error",
+ {
+ "parseAppInfo": false
+ }
+ ],
+ "import/no-unresolved": [
+ "error",
+ {
+ "ignore": [
+ "\\?raw$"
+ ]
+ }
+ ]
+ }
}
diff --git a/.gitignore b/.gitignore
index 38b2456656..c94a5d1e4e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -32,3 +32,5 @@ styleguide/index.html
/playwright-report/
/blob-report/
/tests/component/setup/.cache/
+
+*storybook.log
\ No newline at end of file
diff --git a/.storybook/globals.mock.ts b/.storybook/globals.mock.ts
new file mode 100644
index 0000000000..dc13ce8663
--- /dev/null
+++ b/.storybook/globals.mock.ts
@@ -0,0 +1,110 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+/**
+ * From server util.js
+ *
+ * @param {string} t The string to chunkify
+ * @return {Array}
+ */
+function chunkify(t) {
+ // Adapted from http://my.opera.com/GreyWyvern/blog/show.dml/1671288
+ const tz = []
+ let x = 0
+ let y = -1
+ let n = 0
+ let c
+
+ while (x < t.length) {
+ c = t.charAt(x) // only include the dot in strings
+
+ const m = !n && (c === '.' || (c >= '0' && c <= '9'))
+
+ if (m !== n) {
+ // next chunk
+ y++
+ tz[y] = ''
+ n = m
+ }
+
+ tz[y] += c
+ x++
+ }
+
+ return tz
+}
+
+// Global variables
+window._oc_webroot = ''
+
+window.OC = {
+ debug: true,
+ getCurrentUser() {
+ return {
+ uid: 'admin',
+ displayName: 'Administrator',
+ }
+ },
+ generateUrl() {
+ return 'https://raw.githubusercontent.com/nextcloud/promo/master/nextcloud-icon.png'
+ },
+ getLanguage() {
+ return 'en'
+ },
+ isUserAdmin() {
+ return true
+ },
+ config: {},
+ Util: {
+ /**
+ * Compare two strings to provide a natural sort
+ *
+ * @param {string} a first string to compare
+ * @param {string} b second string to compare
+ * @return {number} -1 if b comes before a, 1 if a comes before b
+ * or 0 if the strings are identical
+ */
+ naturalSortCompare: function naturalSortCompare(a, b) {
+ let x
+ const aa = chunkify(a)
+ const bb = chunkify(b)
+
+ for (x = 0; aa[x] && bb[x]; x++) {
+ if (aa[x] !== bb[x]) {
+ const aNum = Number(aa[x])
+ const bNum = Number(bb[x]) // note: == is correct here
+
+ /* eslint-disable-next-line */
+ if (aNum == aa[x] && bNum == bb[x]) {
+ return aNum - bNum
+ } else {
+ // Note: This locale setting isn't supported by all browsers but for the ones
+ // that do there will be more consistency between client-server sorting
+ return aa[x].localeCompare(bb[x], OC.getLanguage())
+ }
+ }
+ }
+
+ return aa.length - bb.length
+ },
+ },
+ coreApps: [
+ '',
+ 'admin',
+ 'log',
+ 'core/search',
+ 'core',
+ '3rdparty',
+ ],
+ appswebroots: {
+ calendar: '/apps/calendar',
+ deck: '/apps/deck',
+ files: '/apps/files',
+ spreed: '/apps/spreed',
+ },
+ webroot: '',
+}
+window.OCA = {}
+window.appName = 'nextcloud-vue'
diff --git a/.storybook/http.mock.ts b/.storybook/http.mock.ts
new file mode 100644
index 0000000000..bb68582215
--- /dev/null
+++ b/.storybook/http.mock.ts
@@ -0,0 +1,41 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+// A copy of styleguide/global.requires.js
+// TODO: use proper mocking with msw.io
+// @ts-nocheck
+
+import axios from '@nextcloud/axios'
+
+const USER_GROUPS = [
+ { id: 'admin', displayname: 'The administrators' },
+ { id: 'accounting', displayname: 'Accounting team' },
+ { id: 'developer', displayname: 'Engineering team' },
+ { id: 'support', displayname: 'Support crew' },
+ { id: 'users', displayname: 'users' },
+]
+
+/**
+ * Mock some requests for docs
+ *
+ * @param {object} error Axios error
+ */
+function mockRequests(error) {
+ const { request } = error
+ let data = null
+
+ // Mock requesting groups
+ const requestGroups = request.responseURL.match(/cloud\/groups\/details\?search=([^&]*)&limit=\d+$/)
+ if (requestGroups) {
+ data = { groups: USER_GROUPS.filter(e => !requestGroups[1] || e.displayname.startsWith(requestGroups[1]) || e.id.startsWith(requestGroups[1])) }
+ }
+
+ if (data) {
+ return Promise.resolve({ data: { ocs: { data } } })
+ }
+ return Promise.reject(error)
+}
+
+axios.interceptors.response.use((r) => r, e => mockRequests(e))
diff --git a/.storybook/main.ts b/.storybook/main.ts
new file mode 100644
index 0000000000..ac2769755f
--- /dev/null
+++ b/.storybook/main.ts
@@ -0,0 +1,24 @@
+import type { StorybookConfig } from '@storybook/vue3-vite'
+
+const config: StorybookConfig = {
+ stories: ['../docs/**/*.mdx', '../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+
+ addons: [
+ // Collection of essential addons like actions, controls, backgrounds, viewport, etc.
+ '@storybook/addon-essentials',
+ // Links between stories
+ '@storybook/addon-links',
+ // Allows to see and edit the source code of a story
+ '@storybook/addon-storysource',
+ ],
+
+ framework: {
+ name: '@storybook/vue3-vite',
+ options: {
+ // vue-component-meta is recommended for Vue 3 and will be the default in the future
+ docgen: 'vue-component-meta',
+ },
+ },
+}
+
+export default config
diff --git a/.storybook/preview.ts b/.storybook/preview.ts
new file mode 100644
index 0000000000..66d88ba110
--- /dev/null
+++ b/.storybook/preview.ts
@@ -0,0 +1,34 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import type { Preview } from '@storybook/vue3'
+
+import './styles.mock.ts'
+import './http.mock.ts'
+import './globals.mock.ts'
+
+const preview: Preview = {
+ parameters: {
+ controls: {
+ matchers: {
+ color: /(background|color)$/i,
+ date: /Date$/i,
+ },
+ },
+ },
+
+ decorators: [
+ (_, { parameters }) => {
+ const { pageLayout } = parameters
+ // TODO: add layouts for app navigation/sidebar
+ switch (pageLayout) {
+ default:
+ return { template: `
` }
+ }
+ },
+ ]
+}
+
+export default preview
diff --git a/.storybook/styles.css b/.storybook/styles.css
new file mode 100644
index 0000000000..405f7a8092
--- /dev/null
+++ b/.storybook/styles.css
@@ -0,0 +1,5 @@
+[data-server-root] {
+ width: auto !important;
+ height: auto !important;
+ position: static !important;
+}
diff --git a/.storybook/styles.mock.ts b/.storybook/styles.mock.ts
new file mode 100644
index 0000000000..ec380d495f
--- /dev/null
+++ b/.storybook/styles.mock.ts
@@ -0,0 +1,10 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import '../styleguide/assets/default.css'
+import '../styleguide/assets/dark.css'
+import '../styleguide/assets/server.css'
+import '../styleguide/assets/apps.css'
+import './styles.css'
diff --git a/README.md b/README.md
index d123a70183..423f5d9ca7 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,7 @@ Our awesome translation community will then be notified and a bot will sync thos
Nonetheless, it requires a bit of caution.
When you implement a translated string, import the `translate` or `translatePlural` and add it in your methods like so:
+
```vue
@@ -93,6 +94,7 @@ export default {
Please note that using a translated string as an attribute will _NOT_ work.
But it will work if it's within an element (like the example above)
+
```vue
@@ -100,6 +102,7 @@ But it will work if it's within an element (like the example above)
```
You will instead have to define the string in the data section and use the relevant variable reference.
+
```vue
diff --git a/docs/Proposal.mdx b/docs/Proposal.mdx
new file mode 100644
index 0000000000..57f69733da
--- /dev/null
+++ b/docs/Proposal.mdx
@@ -0,0 +1,83 @@
+{/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */}
+
+import { Meta } from '@storybook/blocks'
+
+
+
+# Documentation proposals
+
+## Problem 1: documentation tooling
+
+### Proposal : Migrate from `vue-stylegudist` to `storybook`
+
+### ✅ Props
+
+- Better Vue support without custom API
+- Better UI out of the box
+- Easier to extend:
+ - Light/dark theme switch
+ - Nextcloud 29 / Nextcloud 30 switch
+- Reuse stories with e2e testing in Playwright
+- Addons:
+ - Figma integration
+ - A11y testing
+- De-facto standard for frontend docs
+
+## ❌ Cons
+
+- More complex docs structure - wrinting stories with a huge boilerplate
+- MDX with JSX syntax and React inside
+- More ways to write docs
+- Not easy to support Vue 2 + Vue 3
+
+### Migration component docs from `styleguidist` to `storybook`
+
+1. Add `.stories.ts` file next to the component
+2. Define component name, including categories
+3. If component doesn't use `
-
-
-```
-
-### Alignment
-Sometimes it is required to change the icon alignment on the button, like for switching between pages as in following example:
-
-```vue
-
-
-
-
-```
-
-### Pressed state
-
-It is possible to make the button stateful by adding a pressed state, e.g. if you like to create a favorite button.
-The button will have the required `aria` attribute for accessibility and visual style (`primary` when pressed, and the configured type otherwise).
-
-Do not change `text` or `aria-label` of the pressed/unpressed button. See: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-pressed
-
-```vue
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- Favorite
-
-
-
-
-
-
-
-
-
- It is {{ isFavorite ? 'a' : 'not a' }} favorite.
-
-
-
-
-```
-
-### Usage example: Sorting table columns
-The standard way to implement sortable table column headers should be like this:
-
-```vue
-
-