feat(models): add optional table title

Author: matejchalk

packages/models/docs/models-reference.md

@@ -6,10 +6,10 @@ Detailed information
 
 _Object containing the following properties:_
 
-| Property | Description               | Type                                                                                                                                                                                                                                       |
-| :------- | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `issues` | List of findings          | _Array of [Issue](#issue) items_                                                                                                                                                                                                           |
-| `table`  | Table of related findings | _Object with properties:_<ul><li>`headings`: _Array of [TableHeading](#tableheading) items_</li><li>`alignment`: `Array<'l' \| 'c' \| 'r'>`</li><li>`rows`: `Array<Array<string \| number> \| Record<string, string \| number>>`</li></ul> |
+| Property | Description               | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| :------- | :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `issues` | List of findings          | _Array of [Issue](#issue) items_                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `table`  | Table of related findings | _Object with properties:_<ul><li>`title`: `string` - Display title for table</li><li>`columns`: _Array of [TableAlignment](#tablealignment) items_</li><li>`rows`: _Array of [TableRowPrimitive](#tablerowprimitive) items_</li></ul> _or_ _Object with properties:_<ul><li>`title`: `string` - Display title for table</li><li>`columns`: _Array of [TableAlignment](#tablealignment) items_ _or_ _Array of [TableColumnObject](#tablecolumnobject) items_</li><li>`rows`: _Array of [TableRowObject](#tablerowobject) items_</li></ul> |
 
 _All properties are optional._
 
@@ -1193,6 +1193,13 @@ _Object containing the following properties:_
 
 _(\*) Required._
 
+## PrimitiveValue
+
+_Union of the following possible types:_
+
+- `string`
+- `number`
+
 ## Report
 
 _Object containing the following properties:_
@@ -1253,19 +1260,53 @@ _Returns:_
 
 - [AuditOutputs](#auditoutputs) _or_ _Promise of_ [AuditOutputs](#auditoutputs)
 
-## TableHeading
+## TableAlignment
+
+Cell alignment
+
+_Enum string, one of the following possible values:_
+
+- `'left'`
+- `'center'`
+- `'right'`
 
-Source file location
+## TableColumnObject
 
 _Object containing the following properties:_
 
-| Property       | Type     |
-| :------------- | :------- |
-| **`key`** (\*) | `string` |
-| `label`        | `string` |
+| Property       | Description    | Type                              |
+| :------------- | :------------- | :-------------------------------- |
+| **`key`** (\*) |                | `string`                          |
+| `label`        |                | `string`                          |
+| `align`        | Cell alignment | [TableAlignment](#tablealignment) |
 
 _(\*) Required._
 
+## TableColumnPrimitive
+
+Cell alignment
+
+_Enum string, one of the following possible values:_
+
+- `'left'`
+- `'center'`
+- `'right'`
+
+## TableRowObject
+
+Object row
+
+_Object record with dynamic keys:_
+
+- _keys of type_ `string`
+- _values of type_ [PrimitiveValue](#primitivevalue)
+
+## TableRowPrimitive
+
+Primitive row
+
+_Array of [PrimitiveValue](#primitivevalue) items._
+
 ## UploadConfig
 
 _Object containing the following properties:_

packages/models/src/lib/table.ts

@@ -26,25 +26,34 @@ export const tableRowPrimitiveSchema = z.array(primitiveValueSchema, {
 });
 export type TableRowPrimitive = z.infer<typeof tableRowPrimitiveSchema>;
 
-const tablePrimitiveSchema = z.object(
-  {
-    columns: z.array(tableAlignmentSchema).optional(),
-    rows: z.array(tableRowPrimitiveSchema),
-  },
-  { description: 'Table with primitive rows and optional alignment columns' },
+const tableSharedSchema = z.object({
+  title: z.string().optional().describe('Display title for table'),
+});
+const tablePrimitiveSchema = tableSharedSchema.merge(
+  z.object(
+    {
+      columns: z.array(tableAlignmentSchema).optional(),
+      rows: z.array(tableRowPrimitiveSchema),
+    },
+    { description: 'Table with primitive rows and optional alignment columns' },
+  ),
 );
-
-const tableObjectSchema = z.object(
-  {
-    columns: z
-      .union([z.array(tableAlignmentSchema), z.array(tableColumnObjectSchema)])
-      .optional(),
-    rows: z.array(tableRowObjectSchema),
-  },
-  {
-    description:
-      'Table with object rows and optional alignment or object columns',
-  },
+const tableObjectSchema = tableSharedSchema.merge(
+  z.object(
+    {
+      columns: z
+        .union([
+          z.array(tableAlignmentSchema),
+          z.array(tableColumnObjectSchema),
+        ])
+        .optional(),
+      rows: z.array(tableRowObjectSchema),
+    },
+    {
+      description:
+        'Table with object rows and optional alignment or object columns',
+    },
+  ),
 );
 
 export const tableSchema = (description = 'Table information') =>

packages/models/src/lib/table.unit.test.ts

@@ -163,6 +163,7 @@ describe('tableSchema', () => {
 
   it('should parse complete table', () => {
     const fullTable: Table = {
+      title: 'Largest Contentful Paint element',
       columns: [
         // center is often the default when rendering in MD or HTML
         { key: 'phase', label: 'Phase' },