garage-week/storybook enhancements for future docs site

.cursor/rules/storybook-mdx-conversion.mdc

@@ -0,0 +1,117 @@
+# Storybook MDX conversion
+
+Converts markdown files to MDX format compatible with Storybook rendering.
+
+## When to apply
+
+Apply this rule when converting `.md` files to `.mdx` files for display in Storybook, particularly for documentation pages in the 2nd-gen SWC Storybook guides.
+
+## Conversion steps
+
+### 1. File extension and imports
+
+- Change file extension from `.md` to `.mdx`
+- Add Storybook imports at the top of the file:
+
+```typescript
+import { Meta } from '@storybook/addon-docs/blocks';
+```
+
+- Add a blank line after imports
+
+### 2. Meta tag
+
+- Add a `<Meta title="Your Title Here" />` tag after the imports
+- The title should match the document's main heading
+- Add a blank line after the Meta tag
+
+### 3. Convert HTML comments to JSX comments
+
+Replace HTML comments with JSX-style comments:
+
+**Before (Markdown):**
+
+```markdown
+<!-- Document title (editable) -->
+```
+
+**After (MDX):**
+
+```mdx
+{/* Document title (editable) */}
+```
+
+### 4. Preserve all other content
+
+- Keep all markdown syntax as-is (headings, lists, links, code blocks, etc.)
+- Keep all `<details>` and `<summary>` HTML elements unchanged
+- Keep all list formatting and indentation unchanged
+- Preserve all relative link paths (e.g., `./01_contributor-guides/README.md`)
+- Do not modify any content within `<details>` blocks or navigation lists
+
+## Example transformation
+
+**Before (README.md):**
+
+```markdown
+<!-- Document title (editable) -->
+
+# Contributor Documentation
+
+<!-- Generated TOC - DO NOT EDIT -->
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [About Spectrum Web Components](#about-spectrum-web-components)
+
+</details>
+
+<!-- Document content (editable) -->
+
+## About Spectrum Web Components
+
+Content here...
+```
+
+**After (README.mdx):**
+
+```mdx
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Contributor Documentation" />
+{/* Document title (editable) */}
+
+# Contributor Documentation
+
+{/* Generated TOC - DO NOT EDIT */}
+
+<details open>
+<summary><strong>In this doc</strong></summary>
+
+- [About Spectrum Web Components](#about-spectrum-web-components)
+
+</details>
+
+{/* Document content (editable) */}
+
+## About Spectrum Web Components
+
+Content here...
+```
+
+## Critical rules
+
+1. **Only add imports and Meta tag** - Do not modify any other structural elements
+2. **Preserve exact formatting** - Keep all whitespace, indentation, and line breaks
+3. **Convert ALL HTML comments** - Every `<!-- comment -->` must become `{/* comment */}`
+4. **Keep markdown links** - Do not convert `.md` links to `.mdx` (Storybook may need the original paths)
+5. **Blank lines matter** - Maintain blank line after imports and after Meta tag
+
+## Common mistakes to avoid
+
+❌ Don't change the document's heading structure
+❌ Don't modify navigation lists or TOC content
+❌ Don't convert markdown to JSX (keep lists as markdown lists)
+❌ Don't add extra formatting or styling
+❌ Don't forget to convert ALL HTML comments to JSX comments

.vscode/extensions.json

@@ -1,3 +1,6 @@
 {
-    "recommendations": ["runem.lit-plugin"]
+    "recommendations": [
+        "runem.lit-plugin",
+        "bierner.jsdoc-markdown-highlighting"
+    ]
 }

.vscode/local-extensions/README.md

@@ -0,0 +1,9 @@
+# Installing local extensions in Cursor
+
+The extensions in this directory are not available in Cursor but are in VSCode. The `vsix` file can be uploaded to Cursor locally to install the extension for usage.
+
+The following steps will get you started:
+
+1. Go to cursor, hit Cmd + Shift + P
+2. Search for “Extensions: Install from VSIX…”
+3. Select the extension file from this directory and download

.vscode/settings.json

@@ -31,5 +31,10 @@
     },
     "typescript.tsdk": "node_modules/typescript/lib",
     "lit-plugin.strict": true,
-    "cSpell.words": ["activedescendant", "coachmark", "valuetext"]
+    "cSpell.words": ["activedescendant", "AUTODOCS", "coachmark", "valuetext"],
+    "[mdx]": {
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": "never"
+        }
+    }
 }

2nd-gen/packages/core/components/badge/Badge.types.ts

@@ -14,6 +14,10 @@
  * @todo The S1 types can be removed once we are no longer maintaining 1st-gen.
  */
 
+import type { ElementSize } from '@spectrum-web-components/core/shared/base/index.js';
+
+export const VALID_SIZES: ElementSize[] = ['s', 'm', 'l'] as const;
+
 export const FIXED_VALUES = [
     'inline-start',
     'inline-end',

2nd-gen/packages/core/components/divider/Divider.types.ts

@@ -16,3 +16,5 @@ export const DIVIDER_VALID_SIZES: ElementSize[] = ['s', 'm', 'l'] as const;
 export const DIVIDER_STATIC_COLORS = ['white', 'black'] as const;
 
 export type DividerStaticColor = (typeof DIVIDER_STATIC_COLORS)[number];
+
+export type DividerSize = (typeof DIVIDER_VALID_SIZES)[number];

2nd-gen/packages/core/components/progress-circle/ProgressCircle.base.ts

@@ -20,6 +20,7 @@ import { getLabelFromSlot } from '@spectrum-web-components/core/shared/get-label
 
 import {
     PROGRESS_CIRCLE_VALID_SIZES,
+    ProgressCircleSize,
     ProgressCircleStaticColor,
 } from './ProgressCircle.types.js';
 
@@ -40,7 +41,7 @@ import {
  * @fires progress-change - Dispatched when the progress value changes
  */
 export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
-    validSizes: PROGRESS_CIRCLE_VALID_SIZES,
+    validSizes: PROGRESS_CIRCLE_VALID_SIZES as ProgressCircleSize[],
 }) {
     // ─────────────────────────
     //     API TO OVERRIDE
@@ -89,6 +90,7 @@ export abstract class ProgressCircleBase extends SizedMixin(SpectrumElement, {
      * Accessible label for the progress circle.
      *
      * Used to provide context about what is loading or progressing.
+     * @required for accessibility
      */
     @property({ type: String })
     public label = '';

2nd-gen/packages/core/components/progress-circle/ProgressCircle.types.ts

@@ -30,3 +30,4 @@ export type ProgressCircleStaticColorS2 =
 export type ProgressCircleStaticColor =
     | ProgressCircleStaticColorS1
     | ProgressCircleStaticColorS2;
+export type ProgressCircleSize = (typeof PROGRESS_CIRCLE_VALID_SIZES)[number];

2nd-gen/packages/core/shared/base/version.ts

@@ -9,6 +9,5 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-
 // Generated by genversion.
 export const version = '1.10.0';

2nd-gen/packages/core/shared/utilities/capitalize.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+/**
+ * Capitalizes the first character of a string.
+ *
+ * @param str - The string to capitalize
+ * @returns The capitalized string, or an empty string if the input is not a string
+ *
+ * @example
+ * ```typescript
+ * capitalize('hello') // Returns: 'Hello'
+ * capitalize('world') // Returns: 'World'
+ * capitalize('') // Returns: ''
+ * capitalize(undefined) // Returns: ''
+ * ```
+ */
+export function capitalize(str?: string): string {
+    if (typeof str !== 'string') {
+        return '';
+    }
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}

2nd-gen/packages/core/shared/utilities/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export { capitalize } from './capitalize.js';

2nd-gen/packages/swc/.storybook/DocumentTemplate.mdx

@@ -0,0 +1,63 @@
+import {
+    Meta,
+    Title,
+    Primary,
+    Controls,
+    Stories,
+    ArgTypes,
+    Description,
+    Subtitle,
+    useOf,
+} from '@storybook/addon-docs/blocks';
+import {
+    GettingStarted,
+    SpectrumDocs,
+    SpectrumStories,
+    StaticPrimaryStory,
+} from './blocks';
+import '@spectrum-web-components/tabs/sp-tabs.js';
+import '@spectrum-web-components/tabs/sp-tab.js';
+import '@spectrum-web-components/tabs/sp-tab-panel.js';
+
+export const checkIsSingleStory = () => {
+    const resolvedOf = useOf('meta', ['meta']);
+    const { stories } = resolvedOf.csfFile;
+    const visibleStories = Object.values(stories).filter((story) =>
+        story.tags?.includes('autodocs' || 'dev')
+    );
+    return visibleStories.length === 1;
+};
+
+export const SingleStoryDescription = () => {
+    const isSingleStory = checkIsSingleStory();
+
+    return (isSingleStory ? <Description of="story" /> : null)
+
+}
+
+export const AdvancedExamplesStories = () => {
+    const isSingleStory = checkIsSingleStory();
+
+    return (isSingleStory ? null : <Stories includePrimary={false} />)
+
+}
+
+<Meta isTemplate />
+
+<Title />
+<Subtitle />
+<Description />
+<SingleStoryDescription />
+<StaticPrimaryStory />
+<GettingStarted />
+<SpectrumDocs tag="usage" />
+
+## API
+
+<Primary />
+<Controls />
+<AdvancedExamplesStories />
+
+## Feedback
+
+Have feedback or questions? [Open an issue](https://github.com/adobe/spectrum-web-components/issues/new/choose).