#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:

package.json

@@ -120,7 +120,6 @@
 		"@iconify/json": "2.2.481",
 		"@rolldown/plugin-babel": "^0.2.3",
 		"@storybook/addon-docs": "10.4.2",
-		"@storybook/addon-links": "10.4.2",
 		"@storybook/web-components-vite": "10.4.2",
 		"@tailwindcss/vite": "^4.3.0",
 		"@testing-library/dom": "^10.4.1",

src/components/account/Account.stories.ts

@@ -1,22 +1,21 @@
 import { html } from 'lit'
-import { USER_OPTIONS, defineAuthStoryRender } from '@/storybook'
+import { USER_OPTIONS } from '@/storybook'
 
 import './Account'
 
 const meta = {
-  title: 'Account',
+  title: 'Solid/Account',
   args: {
     user: 'Alice',
   },
   argTypes: {
     user: USER_OPTIONS.control,
-  }
+  },
+  render: () => html`<solid-ui-account></solid-ui-account>`
 } as const
 
-const render = defineAuthStoryRender(() => html`<solid-ui-account></solid-ui-account>`)
-
-export const Primary = { render }
-export const Guest = { render, args: { user: 'Guest' } }
-export const Initializing = { render, args: { user: 'Initializing' } }
+export const Primary = {}
+export const Guest = { args: { user: 'Guest' } }
+export const Initializing = { args: { user: 'Initializing' } }
 
 export default meta

src/components/avatar/Avatar.stories.ts

@@ -1,22 +1,21 @@
 import { html } from 'lit'
-import { USER_OPTIONS, defineAuthStoryRender } from '@/storybook'
+import { USER_OPTIONS } from '@/storybook'
 
 import './Avatar'
 
 const meta = {
-  title: 'Avatar',
+  title: 'Solid/Avatar',
   args: {
     user: 'Alice',
   },
   argTypes: {
     user: USER_OPTIONS.control,
-  }
+  },
+  render: () => html`<solid-ui-avatar></solid-ui-avatar>`
 } as const
 
-const render = defineAuthStoryRender<typeof meta.argTypes>(() => html`<solid-ui-avatar></solid-ui-avatar>`)
-
-export const Primary = { render }
-export const Fallback = { render, args: { user: 'Bob' } }
-export const Guest = { render, args: { user: 'Guest' } }
+export const Primary = {}
+export const Fallback = { args: { user: 'Bob' } }
+export const Guest = { args: { user: 'Guest' } }
 
 export default meta

src/components/button/Button.stories.ts

@@ -1,6 +1,6 @@
 import { html, nothing } from 'lit'
 import { unsafeHTML } from 'lit/directives/unsafe-html.js'
-import { defineControlOptions, defineStoryRender } from '@/storybook'
+import { defineControlOptions } from '@/storybook'
 
 import '~icons/lucide/check'
 import '~icons/lucide/plus'
@@ -17,17 +17,20 @@ const ICON_OPTIONS = defineControlOptions([
   ['None', null]
 ])
 
+const args = {
+  text: 'Save Changes',
+  title: '',
+  variant: 'primary',
+  icon: 'None',
+  leftIcon: 'None',
+  rightIcon: 'None',
+  disabled: false,
+  loading: false,
+} as const
+
 const meta = {
-  title: 'Button',
-  args: {
-    text: 'Save Changes',
-    title: '',
-    variant: 'primary',
-    leftIcon: 'None',
-    rightIcon: 'None',
-    disabled: false,
-    loading: false,
-  },
+  title: 'Basic UI/Button',
+  args,
   argTypes: {
     variant: {
       control: 'select',
@@ -41,37 +44,32 @@ const meta = {
     disabled: { control: 'boolean' },
     loading: { control: 'boolean' },
   },
-} as const
-
-const render = defineStoryRender<typeof meta.argTypes>(({ text, title, variant, icon, leftIcon, rightIcon, disabled, loading }) => {
-  const resolvedIcon = ICON_OPTIONS.resolve(icon)
-  const resolvedLeftIcon = ICON_OPTIONS.resolve(leftIcon)
-  const resolvedRightIcon = ICON_OPTIONS.resolve(rightIcon)
+  render ({ icon, leftIcon, rightIcon, variant, disabled, loading, title, text }: typeof args) {
+    const resolvedIcon = ICON_OPTIONS.resolve(icon)
+    const resolvedLeftIcon = ICON_OPTIONS.resolve(leftIcon)
+    const resolvedRightIcon = ICON_OPTIONS.resolve(rightIcon)
 
-  return html`
-        <solid-ui-button variant="${variant}" .disabled=${disabled} ?loading=${loading} title=${title}>
+    return html`
+        <solid-ui-button variant="${variant}" .disabled=${disabled} ?loading=${loading} title=${title || nothing}>
             ${resolvedLeftIcon ? unsafeHTML(`<icon-lucide-${resolvedLeftIcon} slot="left-icon"></icon-lucide-${resolvedLeftIcon}>`) : nothing}
             ${resolvedIcon ? unsafeHTML(`<icon-lucide-${resolvedIcon} slot="icon"></icon-lucide-${resolvedIcon}>`) : nothing}
             ${text}
             ${resolvedRightIcon ? unsafeHTML(`<icon-lucide-${resolvedRightIcon} slot="right-icon"></icon-lucide-${resolvedRightIcon}>`) : nothing}
         </solid-ui-button>
     `
-})
-
-export default meta
+  }
+} as const
 
-export const Primary = { render }
+export const Primary = {}
 
 export const Secondary = {
-  render,
   args: {
     text: 'Cancel',
     variant: 'secondary'
   },
 }
 
 export const Tertiary = {
-  render,
   args: {
     text: 'Add More',
     variant: 'tertiary',
@@ -80,7 +78,6 @@ export const Tertiary = {
 }
 
 export const Outline = {
-  render,
   args: {
     text: 'Sign Up',
     variant: 'outline',
@@ -89,11 +86,12 @@ export const Outline = {
 }
 
 export const Ghost = {
-  render,
   args: {
     text: '',
     variant: 'ghost',
     icon: 'Help',
     title: 'Open help',
   },
 }
+
+export default meta