From 6d7a94ab7d40dd26c8dbfd560b531005cf84bb5a Mon Sep 17 00:00:00 2001
From: jg10 <181532694+jg10-mastodon-social@users.noreply.github.com>
Date: Tue, 8 Jul 2025 22:21:51 +1000
Subject: [PATCH 1/3] doc(pos-list): add table example

---
 .../2_list-composition.stories.mdx            | 48 ++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/storybook/stories/composition/2_list-composition.stories.mdx b/storybook/stories/composition/2_list-composition.stories.mdx
index edcf3164..a0721399 100644
--- a/storybook/stories/composition/2_list-composition.stories.mdx
+++ b/storybook/stories/composition/2_list-composition.stories.mdx
@@ -10,7 +10,8 @@ import { Canvas, Meta, Story } from "@storybook/addon-docs/blocks";
 ## pos-list composition
 
 This is an example of how you can use `<pos-list>` element to list things
-related to a resource with a custom display.
+related to a resource with a custom display. The `ul` and `li` elements are used
+as appropriate semantic HTML elements.
 
 <Canvas withSource="open">
   <Story name="pos-list composition">
@@ -35,3 +36,48 @@ Skills:
     `}
   </Story>
 </Canvas>
+
+## Table example
+
+The `table`-related HTML elements have strict rules that prevent other elements
+such as `pos-list` being used within them. Instead we can make a table using CSS
+`grid` rules. The grid needs to be defined within each template as `pos-list`
+nests list items within `pos-resource` elements, which use shadow dom.
+
+<Canvas withSource="open">
+  <Story name="pos-list table">
+    {({ uri }) => html`
+<style>
+    [role="row"] {
+        display: grid;
+        grid-template-columns: 200px 600px;
+    }
+    .header {
+        font-weight: bold;
+    }
+    [role="gridcell"], [role="columnheader"] {
+        border: 1px solid grey;
+    }
+</style>
+<pos-resource uri=${uri} role="grid" aria-labelledby="skills-caption">
+    <span role="caption" id="skills-caption">Table of skills</span>
+    <div role="row" class="header">
+        <div role="columnheader">Skill</div>
+        <div role="columnheader">URL</div>
+    </div>
+    <pos-list rel="http://schema.org/skills">
+        <template>
+            <div role="row">
+                <pos-list rel="http://www.w3.org/ns/solid/terms#publicId" role="gridcell">
+                    <template>
+                        <pos-label></pos-label>
+                    </template>
+                </pos-list>
+                <pos-value predicate="http://www.w3.org/ns/solid/terms#publicId" role="gridcell" /></pos-value>
+            <div>
+        </template>
+    </pos-list>
+</pos-resource>
+    `}
+  </Story>
+</Canvas>

From db0ae1b50a443a930cc68617cbbf927e616715db Mon Sep 17 00:00:00 2001
From: jg10 <181532694+jg10-mastodon-social@users.noreply.github.com>
Date: Sun, 13 Jul 2025 17:17:59 +1000
Subject: [PATCH 2/3] doc(pos-list): example uses table aria roles

---
 .../stories/composition/2_list-composition.stories.mdx    | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/storybook/stories/composition/2_list-composition.stories.mdx b/storybook/stories/composition/2_list-composition.stories.mdx
index a0721399..4adc4906 100644
--- a/storybook/stories/composition/2_list-composition.stories.mdx
+++ b/storybook/stories/composition/2_list-composition.stories.mdx
@@ -55,11 +55,11 @@ nests list items within `pos-resource` elements, which use shadow dom.
     .header {
         font-weight: bold;
     }
-    [role="gridcell"], [role="columnheader"] {
+    [role="cell"], [role="columnheader"] {
         border: 1px solid grey;
     }
 </style>
-<pos-resource uri=${uri} role="grid" aria-labelledby="skills-caption">
+<pos-resource uri=${uri} role="table" aria-labelledby="skills-caption">
     <span role="caption" id="skills-caption">Table of skills</span>
     <div role="row" class="header">
         <div role="columnheader">Skill</div>
@@ -68,12 +68,12 @@ nests list items within `pos-resource` elements, which use shadow dom.
     <pos-list rel="http://schema.org/skills">
         <template>
             <div role="row">
-                <pos-list rel="http://www.w3.org/ns/solid/terms#publicId" role="gridcell">
+                <pos-list rel="http://www.w3.org/ns/solid/terms#publicId" role="cell">
                     <template>
                         <pos-label></pos-label>
                     </template>
                 </pos-list>
-                <pos-value predicate="http://www.w3.org/ns/solid/terms#publicId" role="gridcell" /></pos-value>
+                <pos-value predicate="http://www.w3.org/ns/solid/terms#publicId" role="cell" /></pos-value>
             <div>
         </template>
     </pos-list>

From 8863bcfd451806182dca689e5bfe232d565f0b00 Mon Sep 17 00:00:00 2001
From: jg10 <181532694+jg10-mastodon-social@users.noreply.github.com>
Date: Sun, 13 Jul 2025 17:20:37 +1000
Subject: [PATCH 3/3] doc(elements): add pos-list table example to changelog

---
 elements/CHANGELOG.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/elements/CHANGELOG.md b/elements/CHANGELOG.md
index a6cd648a..0d96b741 100644
--- a/elements/CHANGELOG.md
+++ b/elements/CHANGELOG.md
@@ -13,6 +13,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
   - `pos-navigation` is now a more complex navigation widget, not just an input field.
   - It is planned to evolve into an Omnibox for searching and navigating in PodOS Browser.
 
+### Changes
+
+- [pos-list](../docs/elements/components/pos-list): Added storybook example using CSS grid and table aria roles
+
 ### Fixed
 
 - [pos-app-browser](../docs/elements/apps/pos-app-browser): prevent error message flashing up while uri is unset on hard refresh