#835 Improve documentation and ergonomics

.storybook/main.ts

@@ -3,10 +3,7 @@ import { mergeConfig } from 'vite'
 
 const config: StorybookConfig = {
   stories: ['../src/**/*.stories.ts'],
-  addons: [
-    '@storybook/addon-links',
-    '@storybook/addon-docs',
-  ],
+  addons: ['@storybook/addon-docs'],
   framework: '@storybook/web-components-vite',
 
   async viteFinal (config) {

.storybook/preview.ts

@@ -1,4 +1,57 @@
+import { withProvider, getThemeColors } from '@/storybook'
+import { definePreview } from '@storybook/web-components-vite'
+import addonDocs from '@storybook/addon-docs'
+
 import '@/styles/theme.css'
 
-export const tags = ['autodocs']
-export const parameters = {}
+export default definePreview({
+  addons: [addonDocs()],
+  tags: ['autodocs'],
+  decorators: [withProvider],
+  parameters: {
+    options: {
+      storySort: {
+        order: ['Basic UI', 'Advanced', 'Solid'],
+      },
+    },
+    docs: {
+      source: {
+        excludeDecorators: true,
+        transform(code) {
+          const MAX_LINE_LENGTH = 120;
+          const lines = code.trim().split('\n');
+          const formattedLines = lines.map(line => {
+            if (line.length <= MAX_LINE_LENGTH) {
+              return line;
+            }
+
+            const baseIndentMatch = line.match(/^\s*/);
+            const baseIndent = baseIndentMatch ? baseIndentMatch[0] : '';
+            const attrIndent = baseIndent + '  ';
+            const formattedLine = line.replace(/ ([a-z0-9-]+=")/gi, `\n${attrIndent}$1`);
+
+            if (formattedLine !== line) {
+              return formattedLine.replace(/>(<\/[a-z0-9-]+>)$/i, `\n${baseIndent}>$1`);
+            }
+
+            return formattedLine;
+          });
+
+          return formattedLines.filter(line => line.trim() !== '').join('\n');
+        },
+      },
+    },
+  },
+  globalTypes: {
+    primaryColor: {
+      description: 'Primary Color',
+      defaultValue: 'purple',
+      toolbar: {
+        title: 'Primary',
+        icon: 'paintbrush',
+        items: getThemeColors().map((color) => ({ label: color.slice(0, 1).toUpperCase() + color.slice(1), value: color })),
+        dynamicTitle: true,
+      },
+    },
+  },
+});

README.md

@@ -69,6 +69,15 @@ import { log } from 'solid-ui'
 log.msg('Hello there!')
 ```
 
+Finally, if you're going to use a component that requires global state (like `<solid-ui-account>` which hooks into authentication), you'll need to wrap your app with `<solid-ui-provider>`:
+
+```html
+<solid-ui-provider>
+    <!-- This will display the logged in user and allow guests to log in -->
+    <solid-ui-account></solid-ui-account>
+</solid-ui-provider>
+```
+
 ## Use directly in a browser
 
 Solid-UI provides **ESM** bundles for direct browser usage. You'll also need to include the CSS styles: