@pure-ds/storybook 0.1.0

package/stories/reference/reference-docs.js

@@ -0,0 +1,302 @@
+import React from 'react';
+import { Title, Subtitle, Description, Primary, Controls, Stories } from '@storybook/blocks';
+import { LitElement, html, nothing } from 'lit';
+import referenceData from '../../dist/pds-reference.json' assert { type: 'json' };
+import {
+  renderMarkdown,
+  renderCode,
+  renderDefault,
+  renderChipList,
+  renderTable,
+  navigateToStory
+} from './reference-helpers.js';
+
+const DOC_STYLE_ID = 'pds-reference-component-docs-styles';
+const DOC_STYLE_CONTENT = `
+  .pds-reference-docs-wrapper {
+    padding: var(--spacing-5);
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-5);
+  }
+
+  .pds-reference-docs-content {
+    display: flex;
+    flex-direction: column;
+    gap: var(--spacing-5);
+  }
+
+  .pds-reference-docs-reset {
+    margin: 0;
+  }
+
+  .pds-reference-docs-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  .pds-reference-docs-pre {
+    margin: 0;
+    padding: var(--spacing-3);
+  }
+
+  .pds-reference-docs-content code {
+    white-space: normal;
+    word-break: break-word;
+  }
+
+  /* Override Storybook autodocs token styles that force nowrap chips */
+  .css-qa4clq :where(li:not(.sb-anchor, .sb-unstyled, .sb-unstyled li)) code {
+    line-height: inherit;
+    margin: 0;
+    padding: 0;
+    white-space: normal !important;
+    border-radius: 0;
+    font-size: inherit;
+    border: none;
+    color: inherit;
+    background-color: transparent;
+  }
+`;
+
+function ensureDocStyles() {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(DOC_STYLE_ID)) return;
+  const style = document.createElement('style');
+  style.id = DOC_STYLE_ID;
+  style.textContent = DOC_STYLE_CONTENT;
+  document.head.append(style);
+}
+
+if (typeof document !== 'undefined') {
+  ensureDocStyles();
+}
+
+class PdsReferenceComponentDocs extends LitElement {
+  static properties = {
+    component: { type: String },
+    data: { type: Object }
+  };
+
+  constructor() {
+    super();
+    this.component = '';
+    this.data = referenceData;
+
+    ensureDocStyles();
+  }
+
+  createRenderRoot() {
+    return this; // Use light DOM so existing design system styles apply.
+  }
+
+  get componentData() {
+    if (!this.component) return null;
+    return this.data?.components?.[this.component] ?? null;
+  }
+
+  render() {
+    const component = this.componentData;
+
+    if (!component) {
+      return html`
+        <article class="card surface-base">
+          <p class="text-muted pds-reference-docs-reset">
+            No reference metadata found for <code>${this.component || '(unknown component)'}</code>.
+            Run <code>npm run build-reference</code> to refresh docs.
+          </p>
+        </article>
+      `;
+    }
+
+    return html`
+      <div class="flex flex-col gap-lg pds-reference-docs-content">
+        ${this.renderHeader(component)}
+        ${component.pdsTags?.length ? this.renderTags(component.pdsTags) : nothing}
+        ${component.description ? this.renderManifestNotes(component.description) : nothing}
+        ${component.notes?.length ? this.renderImplementationNotes(component.notes) : nothing}
+        ${component.ontology ? this.renderOntology(component.ontology) : nothing}
+        ${component.stories?.length ? this.renderStories(component.stories) : nothing}
+        ${this.renderTableSection('Attributes', component.attributes, [
+          { key: 'name', label: 'Attribute', render: (value) => renderCode(value) },
+          { key: 'description', label: 'Description' },
+          { key: 'type', label: 'Type', render: (value) => renderCode(value) },
+          { key: 'default', label: 'Default', render: (value) => renderDefault(value) }
+        ])}
+        ${this.renderTableSection('Properties', component.properties, [
+          { key: 'name', label: 'Property', render: (value) => renderCode(value) },
+          { key: 'type', label: 'Type', render: (value) => renderCode(value) },
+          { key: 'description', label: 'Description' },
+          { key: 'default', label: 'Default', render: (value) => renderDefault(value) }
+        ])}
+        ${this.renderTableSection('Events', component.events, [
+          { key: 'name', label: 'Event', render: (value) => renderCode(value) },
+          { key: 'type', label: 'Type', render: (value) => renderCode(value) },
+          { key: 'description', label: 'Description' }
+        ])}
+        ${this.renderTableSection('Methods', component.methods, [
+          { key: 'name', label: 'Method', render: (value) => renderCode(value) },
+          { key: 'description', label: 'Description' },
+          {
+            key: 'parameters',
+            label: 'Parameters',
+            render: (value) => {
+              if (!value || !value.length) {
+                return html`<span class="text-muted">&#8212;</span>`;
+              }
+              return html`
+                <ul class="pds-reference-docs-list flex flex-col gap-xs">
+                  ${value.map((param) => html`
+                    <li class="flex flex-wrap gap-xs items-baseline">
+                      <code>${param.name}${param.type ? `: ${param.type}` : ''}</code>
+                      ${param.description ? html`<span class="text-muted text-sm">- ${param.description}</span>` : nothing}
+                    </li>
+                  `)}
+                </ul>
+              `;
+            }
+          },
+          { key: 'return', label: 'Returns', render: (value) => renderCode(value) }
+        ])}
+        ${this.renderTableSection('Slots', component.slots, [
+          { key: 'name', label: 'Slot' },
+          { key: 'description', label: 'Description' }
+        ])}
+        ${this.renderTableSection('CSS Parts', component.cssParts, [
+          { key: 'name', label: 'CSS Part' },
+          { key: 'description', label: 'Description' }
+        ])}
+      </div>
+    `;
+  }
+
+  renderHeader(component) {
+    return html`
+      <section class="card surface-base flex flex-col gap-sm">
+        <div class="flex flex-wrap gap-xs">
+          <span class="badge">Web Component</span>
+          ${component.ontology?.id ? html`<span class="badge">${component.ontology.id}</span>` : nothing}
+          ${component.superclass ? html`<span class="badge">extends ${component.superclass}</span>` : nothing}
+        </div>
+        <h2 class="pds-reference-docs-reset">${component.displayName}</h2>
+        <div class="flex flex-wrap gap-sm text-muted text-sm">
+          <span><code>${component.tag}</code></span>
+          ${component.className ? html`<span>class <code>${component.className}</code></span>` : nothing}
+          ${component.sourceModule ? html`<span>${component.sourceModule}</span>` : nothing}
+        </div>
+        ${component.docsDescription ? html`<div>${renderMarkdown(component.docsDescription)}</div>` : nothing}
+      </section>
+    `;
+  }
+
+  renderTags(tags) {
+    return html`
+      <section class="card surface-base flex flex-col gap-sm">
+        <h3 class="pds-reference-docs-reset">Experience Tags</h3>
+        ${renderChipList(tags)}
+      </section>
+    `;
+  }
+
+  renderManifestNotes(description) {
+    return html`
+      <section class="card surface-base flex flex-col gap-sm">
+        <h3 class="pds-reference-docs-reset">Manifest Notes</h3>
+        <pre class="surface-subtle radius-lg text-sm overflow-auto pds-reference-docs-pre">${description}</pre>
+      </section>
+    `;
+  }
+
+  renderImplementationNotes(notes) {
+    return html`
+      <section class="card surface-base flex flex-col gap-xs">
+        <h3 class="pds-reference-docs-reset">Implementation Notes</h3>
+        ${notes.map((note) => html`<p class="text-muted pds-reference-docs-reset">${note}</p>`)}
+      </section>
+    `;
+  }
+
+  renderOntology(ontology) {
+    return html`
+      <section class="card surface-base flex flex-col gap-sm">
+        <h3 class="pds-reference-docs-reset">Ontology</h3>
+        <div class="flex flex-wrap gap-xs items-center">
+          <span class="badge">${ontology.id}</span>
+          ${ontology.name ? html`<span class="badge">${ontology.name}</span>` : nothing}
+        </div>
+        ${ontology.selectors?.length ? html`
+          <div class="flex flex-col gap-xs">
+            <span class="text-muted text-sm">Selectors</span>
+            ${renderChipList(ontology.selectors)}
+          </div>
+        ` : nothing}
+      </section>
+    `;
+  }
+
+  renderStories(stories) {
+    return html`
+      <section class="card surface-base flex flex-col gap-md">
+        <h3 class="pds-reference-docs-reset">Storybook Coverage</h3>
+        <div class="grid grid-auto-md gap-md">
+          ${stories.map((story) => html`
+            <div class="card surface-elevated flex flex-col gap-xs">
+              <a
+                href="/?path=/story/${story.id}"
+                @click=${(event) => this.handleStoryNavigation(event, story.id)}
+              >${story.name}</a>
+              <div class="flex flex-wrap gap-sm text-muted text-sm">
+                <span>${story.id}</span>
+              </div>
+              ${story.description ? html`<p class="text-muted pds-reference-docs-reset">${story.description}</p>` : nothing}
+              ${story.tags?.length ? renderChipList(story.tags) : nothing}
+            </div>
+          `)}
+        </div>
+      </section>
+    `;
+  }
+
+  handleStoryNavigation(event, storyId) {
+    event?.preventDefault?.();
+    event?.stopPropagation?.();
+    navigateToStory(storyId, 'story');
+  }
+
+  renderTableSection(title, items, columns) {
+    if (!items || !items.length) return nothing;
+    return html`
+      <section class="card surface-base flex flex-col gap-sm">
+        <h3 class="pds-reference-docs-reset">${title}</h3>
+        ${renderTable(items, columns)}
+      </section>
+    `;
+  }
+}
+
+if (!customElements.get('pds-reference-component-docs')) {
+  customElements.define('pds-reference-component-docs', PdsReferenceComponentDocs);
+}
+
+export function createComponentDocsPage(tag) {
+  return function ComponentDocsPage() {
+    return React.createElement(
+      React.Fragment,
+      null,
+      React.createElement(Title, null),
+      React.createElement(Subtitle, null),
+      React.createElement(Description, null),
+      React.createElement(Primary, null),
+      React.createElement(Controls, null),
+      React.createElement(
+        'div',
+        {
+          className: 'card surface-elevated pds-reference-docs-wrapper'
+        },
+        React.createElement('pds-reference-component-docs', { component: tag })
+      ),
+      React.createElement(Stories, { includePrimary: false })
+    );
+  };
+}

package/stories/reference/reference-helpers.js

@@ -0,0 +1,310 @@
+import { html, nothing } from 'lit';
+import { addons } from '@storybook/preview-api';
+import { SELECT_STORY } from '@storybook/core-events';
+import { unsafeHTML } from 'lit/directives/unsafe-html.js';
+import showdown from 'showdown';
+
+const REF_HELPER_STYLE_ID = 'pds-reference-helper-styles';
+const REF_HELPER_STYLE_CONTENT = `
+  .pds-reference-docs-pre {
+    margin: 0;
+    padding: var(--spacing-3);
+  }
+`;
+
+function ensureReferenceHelperStyles() {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(REF_HELPER_STYLE_ID)) return;
+  const style = document.createElement('style');
+  style.id = REF_HELPER_STYLE_ID;
+  style.textContent = REF_HELPER_STYLE_CONTENT;
+  document.head.append(style);
+}
+
+if (typeof document !== 'undefined') {
+  ensureReferenceHelperStyles();
+}
+
+const markdown = new showdown.Converter({
+  tables: true,
+  simplifiedAutoLink: true,
+  ghCodeBlocks: true,
+  simpleLineBreaks: true
+});
+
+export function renderMarkdown(text) {
+  if (!text) return nothing;
+  return unsafeHTML(markdown.makeHtml(text));
+}
+
+export function renderCode(value) {
+  if (!value) return html`<span class="text-muted">&#8212;</span>`;
+  return html`<code>${value}</code>`;
+}
+
+export function renderDefault(value) {
+  if (value === undefined || value === null || value === '') {
+    return html`<span class="text-muted">&#8212;</span>`;
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    const unwrapped = trimmed.startsWith('"') && trimmed.endsWith('"')
+      ? trimmed.slice(1, -1)
+      : trimmed;
+    return html`<code>${unwrapped}</code>`;
+  }
+  return html`<code>${String(value)}</code>`;
+}
+
+export function formatTimestamp(timestamp) {
+  if (!timestamp) return '\u2014';
+  try {
+    const date = new Date(timestamp);
+    return date.toLocaleString();
+  } catch (err) {
+    return timestamp;
+  }
+}
+
+const VOID_HTML_ELEMENTS = new Set([
+  'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input',
+  'link', 'meta', 'param', 'source', 'track', 'wbr'
+]);
+
+const getStorySlug = (storyId) => {
+  if (typeof storyId !== 'string') return undefined;
+  const [slug] = storyId.split('--');
+  return slug;
+};
+
+export function navigateToStory(storyId, viewMode = 'story') {
+  if (!storyId || typeof window === 'undefined') return false;
+
+  let navigated = false;
+
+  try {
+    const channel = addons?.getChannel?.();
+    if (channel?.emit) {
+      channel.emit(SELECT_STORY, { storyId, viewMode });
+      navigated = true;
+    }
+  } catch (err) {
+    console.warn('PDS reference docs: channel navigation failed', err);
+  }
+
+  try {
+    window.parent?.postMessage(
+      {
+        source: 'pds-reference-docs',
+        type: 'pds-related:navigate',
+        storyId,
+        viewMode
+      },
+      '*'
+    );
+  } catch (err) {
+    console.warn('PDS reference docs: postMessage navigation failed', err);
+  }
+
+  if (navigated) return true;
+
+  const slug = getStorySlug(storyId);
+  const targetSearch = viewMode === 'docs' && slug
+    ? `?path=/docs/${slug}--docs`
+    : `?path=/story/${storyId}`;
+
+  try {
+    if (window.parent && window.parent !== window) {
+      window.parent.location.search = targetSearch;
+    } else {
+      window.location.search = targetSearch;
+    }
+    return true;
+  } catch (err) {
+    console.warn('PDS reference docs: fallback navigation failed', err);
+  }
+
+  return false;
+}
+
+export function formatDemoHtml(html) {
+  if (typeof html !== 'string') return '';
+  const tokens = html.trim().split(/(<[^>]+>)/g).filter(Boolean);
+  if (!tokens.length) return '';
+
+  const indentUnit = '  ';
+  let indent = 0;
+  let formatted = '';
+
+  for (const token of tokens) {
+    const isTag = token.startsWith('<');
+    if (!isTag) {
+      const text = token.replace(/\s+/g, ' ').trim();
+      if (text) {
+        formatted += `${indentUnit.repeat(indent)}${text}\n`;
+      }
+      continue;
+    }
+
+    const isClosing = /^<\//.test(token);
+    const tagNameMatch = token.match(/^<\/?\s*([a-zA-Z0-9-]+)/);
+    const tagName = tagNameMatch ? tagNameMatch[1].toLowerCase() : '';
+    const isVoid = VOID_HTML_ELEMENTS.has(tagName) || /\/\s*>$/.test(token);
+
+    if (isClosing) {
+      indent = Math.max(0, indent - 1);
+    }
+
+    formatted += `${indentUnit.repeat(indent)}${token.trim()}\n`;
+
+    if (!isClosing && !isVoid) {
+      indent += 1;
+    }
+  }
+
+  return formatted.trimEnd();
+}
+
+export function escapeCodeFragment(text) {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export function highlightDemoHtml(html) {
+  if (!html) return '';
+  let result = '';
+  let index = 0;
+  const attrRegex = /([\w:-@.]+)(?:=(?:"([^"]*)"|'([^']*)'|([^\s>]*)))?/g;
+
+  while (index < html.length) {
+    if (html.startsWith('<!--', index)) {
+      const commentEnd = html.indexOf('-->', index);
+      if (commentEnd !== -1) {
+        const comment = html.substring(index, commentEnd + 3);
+        result += `<span class="html-token-comment">${escapeCodeFragment(comment)}</span>`;
+        index = commentEnd + 3;
+        continue;
+      }
+    }
+
+    const char = html[index];
+
+    if (char === '\n' || char === '\r' || char === '\t' || char === ' ') {
+      result += char;
+      index += 1;
+      continue;
+    }
+
+    if (char === '<') {
+      const tagEnd = html.indexOf('>', index);
+      if (tagEnd !== -1) {
+        const tagContent = html.substring(index + 1, tagEnd);
+        result += '&lt;';
+
+        if (tagContent.startsWith('/')) {
+          const tagName = tagContent.substring(1).split(/[\s>]/)[0];
+          result += '/';
+          result += `<span class="html-token-tag">${escapeCodeFragment(tagName)}</span>`;
+        } else {
+          const parts = tagContent.match(/^([\w:-@.]+)([\s\S]*?)(\/?)?$/);
+          if (parts) {
+            const [, tagName, attrsStr, trailingSlash] = parts;
+            result += `<span class="html-token-tag">${escapeCodeFragment(tagName)}</span>`;
+
+            if (attrsStr && attrsStr.trim()) {
+              let lastIndex = 0;
+              attrRegex.lastIndex = 0;
+              let match;
+
+              while ((match = attrRegex.exec(attrsStr)) !== null) {
+                result += escapeCodeFragment(attrsStr.substring(lastIndex, match.index));
+                const [fullMatch, attrName, doubleQuoted, singleQuoted, unquoted] = match;
+                result += `<span class="html-token-attr">${escapeCodeFragment(attrName)}</span>`;
+
+                if (doubleQuoted !== undefined) {
+                  result += `=<span class="html-token-value">"${escapeCodeFragment(doubleQuoted)}"</span>`;
+                } else if (singleQuoted !== undefined) {
+                  result += `=<span class="html-token-value">'${escapeCodeFragment(singleQuoted)}'</span>`;
+                } else if (unquoted !== undefined && unquoted !== '') {
+                  result += `=<span class="html-token-value">${escapeCodeFragment(unquoted)}</span>`;
+                }
+
+                lastIndex = match.index + fullMatch.length;
+              }
+
+              result += escapeCodeFragment(attrsStr.substring(lastIndex));
+            }
+
+            if (trailingSlash) {
+              result += '/';
+            }
+          } else {
+            result += escapeCodeFragment(tagContent);
+          }
+        }
+
+        result += '&gt;';
+        index = tagEnd + 1;
+        continue;
+      }
+    }
+
+    result += escapeCodeFragment(char);
+    index += 1;
+  }
+
+  return result;
+}
+
+export function renderChipList(values = []) {
+  if (!values.length) return nothing;
+  return html`
+    <div class="flex flex-wrap gap-xs">
+      ${values.map((value) => html`<span class="badge">${value}</span>`)}
+    </div>
+  `;
+}
+
+export function formatTableValue(value) {
+  if (value === undefined || value === null || value === '') {
+    return html`<span class="text-muted">&#8212;</span>`;
+  }
+
+  if (Array.isArray(value)) {
+    if (!value.length) return html`<span class="text-muted">&#8212;</span>`;
+    return renderChipList(value.map((entry) => (typeof entry === 'object' ? JSON.stringify(entry) : entry)));
+  }
+
+  if (typeof value === 'object') {
+    return html`
+      <pre class="surface-subtle radius-lg text-sm overflow-auto pds-reference-docs-pre">
+${JSON.stringify(value, null, 2)}
+      </pre>
+    `;
+  }
+
+  const text = String(value);
+  return /[<>&]/.test(text) ? unsafeHTML(text) : html`${text}`;
+}
+
+export function renderTable(items = [], columns = []) {
+  if (!items.length) return nothing;
+  return html`
+    <table class="table-bordered table-compact">
+      <thead>
+        <tr>
+          ${columns.map((col) => html`<th scope="col">${col.label}</th>`)}
+        </tr>
+      </thead>
+      <tbody>
+        ${items.map((item) => html`
+          <tr>
+            ${columns.map((col) => html`<td>${col.render ? col.render(item[col.key], item) : formatTableValue(col.format ? col.format(item[col.key], item) : item[col.key])}</td>`)}
+          </tr>
+        `)}
+      </tbody>
+    </table>
+  `;
+}