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

packages/components/src/components/post-popover-trigger/readme.md

@@ -0,0 +1,78 @@
+# post-popover
+
+
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property                          | Attribute              | Description                                                                                                                                                                                                                                                                                                                                                                               | Type                                                                                                                                                                 | Default     |
+| --------------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `arrow`                           | `arrow`                | Show a little indicator arrow                                                                                                                                                                                                                                                                                                                                                             | `boolean`                                                                                                                                                            | `true`      |
+| `closeButtonCaption` _(required)_ | `close-button-caption` | Define the caption of the close button for assistive technology                                                                                                                                                                                                                                                                                                                           | `string`                                                                                                                                                             | `undefined` |
+| `placement`                       | `placement`            | Defines the position of the popover relative to its trigger. Popovers are automatically flipped to the opposite side if there is not enough available space and are shifted towards the viewport if they would overlap edge boundaries. For supported values and behavior details, see the [Floating UI placement documentation](https://floating-ui.com/docs/computePosition#placement). | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "left-end" \| "left-start" \| "right" \| "right-end" \| "right-start" \| "top" \| "top-end" \| "top-start"` | `'top'`     |
+
+
+## Methods
+
+### `hide() => Promise<void>`
+
+Programmatically hide this popover
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+### `show(target: HTMLElement) => Promise<void>`
+
+Programmatically display the popover
+
+#### Parameters
+
+| Name     | Type          | Description                                                                  |
+| -------- | ------------- | ---------------------------------------------------------------------------- |
+| `target` | `HTMLElement` | An element with [data-popover-target="id"] where the popover should be shown |
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+### `toggle(target: HTMLElement, force?: boolean) => Promise<void>`
+
+Toggle popover display
+
+#### Parameters
+
+| Name     | Type          | Description                                                                        |
+| -------- | ------------- | ---------------------------------------------------------------------------------- |
+| `target` | `HTMLElement` | An element with [data-popover-target="id"] where the popover should be anchored to |
+| `force`  | `boolean`     | Pass true to always show or false to always hide                                   |
+
+#### Returns
+
+Type: `Promise<void>`
+
+
+
+
+## Dependencies
+
+### Depends on
+
+- [post-popovercontainer](../post-popovercontainer)
+
+### Graph
+```mermaid
+graph TD;
+  post-popover --> post-popovercontainer
+  style post-popover fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

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,73 @@
+export class DemoButton extends HTMLElement {
+  static get observedAttributes() {
+    return ['button-version', 'workaround', 'arialabelledby-id', 'ariadescribedby-id'];
+  }
+  private buttonVersion?: '1' | '2' | '3' | '4';
+  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) {
+    if (name === 'workaround') this.workaround = newValue;
+    if (name === 'arialabelledby-id') this.arialabelledbyId = newValue;
+    if (name === 'ariadescribedby-id') this.ariadescribedbyId = newValue;
+    if (name === 'button-version') this.buttonVersion = newValue as '1' | '2' | '3';
+    this.render();
+  }
+
+  private setupAria() {
+    const isLabelled = this.workaround === 'ariaLabelledByElements';
+    const isDescribed = this.workaround === 'ariaDescribedByElements';
+
+    if (!this.internalButton || (!isLabelled && !isDescribed)) {
+      return;
+    }
+
+    let elementToLink: Element | null = null;
+
+    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;
+      }
+    }
+
+    const ariaPropertyName = isLabelled ? 'ariaLabelledByElements' : 'ariaDescribedByElements';
+    this.internalButton[ariaPropertyName] = elementToLink ? [elementToLink] : [];
+  }
+
+  private render() {
+    if (!this.shadowRoot) return;
+    this.shadowRoot.innerHTML = `
+      <slot name="label-slot"></slot>
+      <div part="button"
+        class="btn btn-primary"
+        role="button"
+        tabindex="0"
+      > <post-icon name="1022"></post-icon>
+      </div>
+    `;
+
+    this.internalButton = this.shadowRoot.querySelector('div[role="button"]') as HTMLElement;
+    this.slotEl = this.shadowRoot.querySelector('slot[name="label-slot"]') as HTMLSlotElement;
+    this.setupAria();
+  }
+}
+
+customElements.define('demo-button', DemoButton);

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,38 @@
+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="demo-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>`;
+    }
+  }
+}
+
+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,41 @@
+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 == 1) {
+      this.shadowRoot.innerHTML = `
+        <div>
+          <slot></slot>
+        </div>
+    `;
+    } else if (this.listVersion == 2) {
+      this.shadowRoot.innerHTML = `
+        <div role="list" tabindex="0">
+          <slot></slot>
+        </div>
+    `;
+    }
+  }
+}
+
+customElements.define('demo-list', DemoList);

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

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