feat(documentation): add accessibility reference relationship stories and demo components

packages/documentation/.storybook/preview.ts

@@ -19,6 +19,8 @@ import './styles/preview.scss';
 import { SyntaxHighlighter } from 'storybook/internal/components';
 import scss from 'react-syntax-highlighter/dist/esm/languages/prism/scss';
 
+import '../src/demo-components';
+
 SyntaxHighlighter.registerLanguage('scss', scss);
 
 export const SourceDarkScheme = true;

packages/documentation/src/demo-components/demo-button.ts

@@ -0,0 +1,99 @@
+type ButtonVersion = '1' | '2' | '3' | '4';
+
+export class DemoButton extends HTMLElement {
+  static get observedAttributes() {
+    return ['button-version', 'workaround', 'arialabelledby-id', 'ariadescribedby-id'];
+  }
+
+  private buttonVersion?: ButtonVersion;
+  private workaround?: string;
+  private internalButton?: HTMLElement;
+  private arialabelledbyId?: string;
+  private ariadescribedbyId?: string;
+  private slotEl?: HTMLSlotElement;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    const member = name.replace(/-([a-z])/g, (_, p) => p.toUpperCase());
+
+    if (member === 'buttonVersion') {
+      this.buttonVersion = newValue as ButtonVersion;
+    } else {
+      this[member as keyof this] = newValue as this[keyof this];
+    }
+
+    this.render();
+  }
+
+  private setupAria() {
+    let elementToLink: Element | null = null;
+
+    const isLabelled = this.workaround === 'ariaLabelledByElements';
+    const isDescribed = this.workaround === 'ariaDescribedByElements';
+
+    const ariaPropertyName = isLabelled ? 'ariaLabelledByElements' : 'ariaDescribedByElements';
+
+    if (!this.internalButton || (!isLabelled && !isDescribed)) {
+      return;
+    }
+
+    if (this.buttonVersion === '1' || this.buttonVersion === '3') {
+      const id = isLabelled ? this.arialabelledbyId : this.ariadescribedbyId;
+      if (id) {
+        elementToLink = document.querySelector(`#${id}`);
+      }
+    } else if (this.buttonVersion === '2' || this.buttonVersion === '4') {
+      if (this.slotEl) {
+        const assignedElements = this.slotEl.assignedElements({ flatten: true });
+        elementToLink = assignedElements.find(el => el.tagName === 'SPAN') || null;
+      }
+    }
+
+    this.internalButton[ariaPropertyName] = elementToLink ? [elementToLink] : [];
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+
+    if (this.buttonVersion) {
+      this.shadowRoot.innerHTML = `
+      <slot name="aria-slot"></slot>
+      <div part="button"
+        role="button"
+        tabindex="0"
+      > <post-icon name="1022"></post-icon>
+      </div>
+    `;
+    } else if (this.arialabelledbyId) {
+      this.shadowRoot.innerHTML = `
+      <span id="${this.arialabelledbyId}">My Text</span>
+      <div part="button"
+      role="button" tabindex="0" aria-labelledby="${this.arialabelledbyId}">
+        <post-icon name="1022"></post-icon>
+      </div>
+   `;
+    } else if (this.ariadescribedbyId) {
+      this.shadowRoot.innerHTML = `
+      <div part="button"
+      role="button" tabindex="0" aria-describedby="${this.ariadescribedbyId}">
+        <post-icon name="1022"></post-icon>
+      </div>
+        <span id="${this.ariadescribedbyId}">My Description</span>
+   `;
+    }
+
+    this.internalButton = this.shadowRoot.querySelector('div[role="button"]') as HTMLElement;
+    this.slotEl = this.shadowRoot.querySelector('slot[name="aria-slot"]') as HTMLSlotElement;
+    this.setupAria();
+  }
+}
+
+customElements.define('demo-button', DemoButton);

packages/documentation/src/demo-components/demo-input.ts

@@ -0,0 +1,90 @@
+export class DemoInput extends HTMLElement {
+  static get observedAttributes() {
+    return ['workaround', 'arialabelledby-id', 'target-version'];
+  }
+
+  private workaround?: string;
+  private arialabelledbyId?: string;
+  private targetVersion?: '1' | '2' | '3';
+  private internalEl?: HTMLElement;
+  private slotEl?: HTMLSlotElement;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    if (name === 'workaround') this.workaround = newValue;
+    if (name === 'arialabelledby-id') this.arialabelledbyId = newValue;
+    if (name === 'target-version') this.targetVersion = newValue as '1' | '2' | '3';
+
+    this.render();
+  }
+
+  private setupAriaLabelledBy() {
+    if (!this.internalEl) {
+      return;
+    }
+
+    let elementToLink: Element | null = null;
+    const isLabelledByWorkaround = this.workaround === 'ariaLabelledByElements';
+
+    if (this.targetVersion === '1') {
+      if (isLabelledByWorkaround && this.arialabelledbyId) {
+        elementToLink = document.querySelector(`[for="${this.arialabelledbyId}"]`);
+      }
+    } else if (this.targetVersion === '2') {
+      if (isLabelledByWorkaround && this.slotEl) {
+        const assignedElements = this.slotEl.assignedElements({ flatten: true });
+        elementToLink = assignedElements.find(el => el.tagName === 'LABEL') || null;
+      }
+    } else if (this.targetVersion === '3') {
+      if (this.arialabelledbyId) {
+        elementToLink = document.querySelector(`#${this.arialabelledbyId}`);
+      }
+    }
+
+    this.internalEl.ariaLabelledByElements = elementToLink ? [elementToLink] : [];
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    //Version #2
+    if (this.targetVersion === '2') {
+      this.shadowRoot.innerHTML = `
+        <slot name="aria-slot"></slot>
+        <input id="internal">
+      `;
+      this.slotEl = this.shadowRoot.querySelector('slot[name="aria-slot"]') as HTMLSlotElement;
+      this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
+    } else if (this.targetVersion === '3') {
+      // Version #3
+      this.shadowRoot.innerHTML = `
+        <input id="internal">
+      `;
+      this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
+    } else if (this.targetVersion === '1') {
+      // Version #1
+      this.shadowRoot.innerHTML = `
+        <input id="internal">
+        <slot></slot>
+      `;
+      this.internalEl = this.shadowRoot.querySelector('#internal') as HTMLElement;
+    } else {
+      // Version default
+      this.shadowRoot.innerHTML = `
+        <label for="example">My Text</label>
+        <input id="example">
+      `;
+    }
+
+    this.setupAriaLabelledBy();
+  }
+}
+
+customElements.define('demo-input', DemoInput);

packages/documentation/src/demo-components/demo-label.ts

@@ -0,0 +1,31 @@
+export class DemoLabel extends HTMLElement {
+  static get observedAttributes() {
+    return ['for'];
+  }
+
+  private for!: string;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    if (name === 'for') this.for = newValue;
+
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    this.shadowRoot.innerHTML = `
+      <label>My Text</label>
+    `;
+  }
+}
+
+customElements.define('demo-label', DemoLabel);

packages/documentation/src/demo-components/demo-list-item-group.ts

@@ -0,0 +1,47 @@
+export class DemoListItemGroup extends HTMLElement {
+  static get observedAttributes() {
+    return ['list-group-version'];
+  }
+
+  private listGroupVersion?: number;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  attributeChangedCallback(name: string, _oldValue: number, newValue: number) {
+    if (name === 'list-group-version') this.listGroupVersion = newValue;
+
+    this.render();
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    if (this.listGroupVersion == 1) {
+      this.shadowRoot.innerHTML = `
+        <slot name="list-item"></slot>
+      `;
+    } else if (this.listGroupVersion == 2) {
+      this.shadowRoot.innerHTML = `<slot name="list-parent"></slot>
+        <div role="listitem">item 1</div>
+        <div role="listitem">item 2</div>
+        <div role="listitem">item 3</div>`;
+    } else if (this.listGroupVersion == 3) {
+      this.shadowRoot.innerHTML = `
+        <div role="listitem">item 1</div>
+        <div role="listitem">item 2</div>
+        <div role="listitem">item 3</div>`;
+    } else if (this.listGroupVersion == 4) {
+      this.shadowRoot.innerHTML = `
+        <slot></slot>
+      `;
+    }
+  }
+}
+
+customElements.define('demo-list-item-group', DemoListItemGroup);

packages/documentation/src/demo-components/demo-list-item.ts

@@ -0,0 +1,20 @@
+export class DemoListItem extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    this.shadowRoot.innerHTML = `
+    <div role="listitem">
+      <slot></slot>
+    </div>`;
+  }
+}
+
+customElements.define('demo-list-item', DemoListItem);

packages/documentation/src/demo-components/demo-list.ts

@@ -0,0 +1,54 @@
+export class DemoList extends HTMLElement {
+  static get observedAttributes() {
+    return ['list-version'];
+  }
+
+  private listVersion?: number;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: number, newValue: number) {
+    if (name === 'list-version') this.listVersion = newValue;
+
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    if (this.listVersion == 0) {
+      this.shadowRoot.innerHTML = `
+        <div role="list" tabindex="0">
+        </div>
+    `;
+    } else if (this.listVersion == 1) {
+      this.shadowRoot.innerHTML = `
+          <slot></slot>
+    `;
+    } else if (this.listVersion == 2) {
+      this.shadowRoot.innerHTML = `
+        <div role="list" tabindex="0">
+          <div role="listitem">item 1</div>
+          <div role="listitem">item 2</div>
+          <div role="listitem">item 3</div>
+        </div>
+    `;
+    } else if (this.listVersion == 3) {
+      this.shadowRoot.innerHTML = `
+        <div role="list" tabindex="0">
+            <slot></slot>
+        </div>
+    `;
+    } else if (this.listVersion == 4) {
+      this.shadowRoot.innerHTML = `<demo-list-item-group list-group-version="3"></demo-list-item-group>`;
+    }
+  }
+}
+
+customElements.define('demo-list', DemoList);

packages/documentation/src/demo-components/demo-span.ts

@@ -0,0 +1,34 @@
+export class DemoSpan extends HTMLElement {
+  static get observedAttributes() {
+    return ['spanId', 'content'];
+  }
+
+  private spanId!: string;
+  private content: string = 'My text';
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  connectedCallback() {
+    this.render();
+  }
+
+  attributeChangedCallback(name: string, _oldValue: string, newValue: string) {
+    if (name === 'id') this.spanId = newValue;
+    if (name === 'content') this.content = newValue;
+
+    this.render();
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+
+    this.shadowRoot.innerHTML = `
+      <span>${this.content}</span>
+    `;
+  }
+}
+
+customElements.define('demo-span', DemoSpan);

packages/documentation/src/demo-components/index.ts

@@ -0,0 +1,7 @@
+import './demo-button';
+import './demo-input';
+import './demo-label';
+import './demo-list';
+import './demo-list-item';
+import './demo-list-item-group';
+import './demo-span';