zz-meridian 0.22.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "Bring ZZ Meridian, a dashboard design system, into a Next.js project, or start a new dashboard on it. Copies the files in; nothing depends on this package at runtime.",
   "license": "MIT",
   "type": "module",

package/payload/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 Every release of ZZ Meridian, newest first. Versions follow semver: a removed or renamed token, prop or card is major; a new card, token or variant is minor; a corrected value is a patch. Each entry says what breaks and what to do instead.
 
+## [0.23.0] · 2026-10-20
+
+### New
+
+- **`Prose` names each body cell's column, and stacks a narrow table into labelled cards** ([#75](https://github.com/zhixuan312/zz-meridian/issues/75)). Every body `td` carries its column's heading as `data-label`, written while the markdown is rendered, so it is in the server's HTML and a page can style a narrow table from `td[data-label]` on the first paint, with no second markdown parser. `stack` does it for you: a table under 480px of its own width reads as one card per row, the header row hidden, the first cell the title and each later cell under its column's heading. Wider, it is the same table; without `stack`, nothing changes.
+
 ## [0.22.0] · 2026-10-20
 
 ### New

package/payload/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zz-meridian-template",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "private": true,
   "license": "MIT",
   "description": "ZZ Meridian: a dashboard design system and starter. Six layers, from DTCG tokens through four layers of React components to product workspaces, and a Design Atlas, in a light and a dark theme.",

package/payload/src/components/patterns/prose/README.md

@@ -10,7 +10,7 @@ Status: beta
 2. **Headings**: the writer's `#` is an h2 (`text-xl`), `##` an h3 with a hairline above it, `###` an h4: the page keeps the only h1.
 3. **Lists**: discs and numbers in `ink-3`; task boxes drawn as checkboxes named "Done" or "Not done".
 4. **Code**: inline on `surface-sunk` with a `line` border; a fenced block on `surface-sunk`, `radius-lg`, wrapping instead of scrolling.
-5. **Tables**: inside a `line`-bordered frame, a `surface-sunk` header row, `text-sm` cells.
+5. **Tables**: inside a `line`-bordered frame, a `surface-sunk` header row, `text-sm` cells. Every body cell carries its column's heading as `data-label`, in the server's HTML. With `stack`, a table under 480px of its own width reads as one card per row: the header row hidden, the first cell the title in `ink`, each later cell under its heading in `text-xs` `ink-3`.
 6. **Quote**: a 2px `accent` rule on the left, `ink` text.
 7. **Links**: `.link`, in `accent-ink`, turning `ink` on hover, never underlined; a link out of the product sends no referrer.
 
@@ -34,6 +34,7 @@ A markdown string. Line endings are normalised and the ends trimmed; nothing els
 | An image from another origin | Its alt text in italics (or "Image not shown"), never fetched |
 | A long token in code or a link: a URL, a path, a hash | Breaks anywhere rather than widen its paragraph or table; plain words wrap between words |
 | A table with more columns than the card holds | Scrolls inside its own frame; the page never scrolls sideways |
+| `stack`, and a table under 480px of its own width | One card per row, each value under its column's heading; no header row |
 | Empty | Nothing: the caller shows the empty state ("No notes yet") |
 
 ## Surfaces
@@ -71,4 +72,7 @@ import { Prose } from '@/components/patterns/prose';
 
 <Card className="p-(--card-pad)"><Prose>{incident.review}</Prose></Card>
 <Prose size="sm">{comment.body}</Prose>
+<Prose stack>{decision.record}</Prose>   // tables become labelled cards in a narrow column
 ```
+
+`stack` is for a document whose tables carry sentences (a decision record, a comparison) read in a narrow column. A table of short figures reads better scrolling in its frame, which is the default. Without `stack`, a page can still style its own narrow layout from `td[data-label]`.

package/payload/src/components/patterns/prose/index.tsx

@@ -1,4 +1,4 @@
-import { memo } from 'react';
+import { memo, type ReactNode } from 'react';
 import ReactMarkdown, { type Components } from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { cn } from '@/lib/cn';
@@ -7,6 +7,25 @@ import { safeMarkdownUrl } from '@/lib/safe-markdown';
 /** A link that leaves the product sends no referrer: the reader's address is not the author's business. */
 const external = (href?: string) => Boolean(href && /^(https?:)?\/\//i.test(href));
 
+type Hast = { type: string; tagName?: string; value?: string; properties?: Record<string, unknown>; children?: Hast[] };
+const text = (n: Hast): string => n.value ?? (n.children ?? []).map(text).join('');
+const elements = (n: Hast, tag: string): Hast[] => (n.children ?? []).flatMap((c) => (c.tagName === tag ? [c] : c.tagName === 'table' ? [] : elements(c, tag)));
+
+/**
+ * Each body cell carries its column's heading as `data-label`, written while the markdown is turned into HTML, so a
+ * table can be read as labelled cards with CSS alone on the server's first paint. A cell past the last heading, or
+ * under an empty one, carries none.
+ */
+const labelCells = () => (tree: Hast) => {
+  for (const table of elements({ type: 'root', children: [tree] }, 'table')) {
+    const headings = elements(table, 'th').map((th) => text(th).trim());
+    for (const tr of elements(table, 'tbody').flatMap((b) => elements(b, 'tr')))
+      elements(tr, 'td').forEach((td, i) => {
+        if (headings[i]) td.properties = { ...td.properties, dataLabel: headings[i] };
+      });
+  }
+};
+
 /**
  * Markdown a person wrote (a document, a note, an agent's reply), set for reading on Meridian's roles: a 72-character
  * measure, quiet tables, code on the sunk surface. Each element is drawn here rather than by a typography plugin, so
@@ -39,7 +58,7 @@ const COMPONENTS: Components = {
   thead: ({ children }) => <thead className="border-b border-line bg-surface-sunk">{children}</thead>,
   th: ({ children }) => <th className="px-3 py-2 text-xs font-medium whitespace-nowrap text-ink-3">{children}</th>,
   tr: ({ children }) => <tr className="border-b border-line last:border-0">{children}</tr>,
-  td: ({ children }) => <td className="px-3 py-2.5 align-top text-ink-2">{children}</td>,
+  td: ({ children, 'data-label': label }: { children?: ReactNode; 'data-label'?: string }) => <td data-label={label} className="px-3 py-2.5 align-top text-ink-2">{children}</td>,
   blockquote: ({ children }) => <blockquote className="my-4 border-l-2 border-accent pl-4 text-ink">{children}</blockquote>,
   hr: () => <hr className="my-8 border-line" />,
   // An image the URL policy dropped reads as its alt text, never as a broken-image icon.
@@ -52,10 +71,36 @@ const COMPONENTS: Components = {
     rest.type === 'checkbox' ? <input {...rest} aria-label={rest.checked ? 'Done' : 'Not done'} className="mr-2 size-3.5 align-[-2px] accent-(--accent)" /> : <input {...rest} />),
 };
 
-export const Prose = memo(function Prose({ children, size = 'base', className }: { children: string; /** `sm` for a side panel, a comment or a quoted body. */ size?: 'base' | 'sm'; className?: string }) {
+/**
+ * `stack`: below 480px of its own width a table reads as one card per row: the header row hidden, the first cell the
+ * card's title, each later cell on its own line under its column's heading. The frame is the container, so a table in a
+ * narrow column stacks wherever the column is narrow, not only on a phone.
+ */
+const STACKED: Components = {
+  ...COMPONENTS,
+  table: ({ children }) => (
+    <div className="my-5 overflow-x-auto rounded-lg border border-line @container">
+      <table className={cn('w-full text-left text-sm leading-normal',
+        '@max-[480px]:block @max-[480px]:[&>thead]:hidden @max-[480px]:[&>tbody]:block @max-[480px]:[&_tr]:block @max-[480px]:[&_tr]:px-3 @max-[480px]:[&_tr]:py-2.5',
+        '@max-[480px]:[&_td]:block @max-[480px]:[&_td]:p-0 @max-[480px]:[&_td+td]:mt-2 @max-[480px]:[&_td:first-child]:font-medium @max-[480px]:[&_td:first-child]:text-ink',
+        '@max-[480px]:[&_td:not(:first-child)[data-label]]:before:block @max-[480px]:[&_td:not(:first-child)[data-label]]:before:text-xs @max-[480px]:[&_td:not(:first-child)[data-label]]:before:font-medium @max-[480px]:[&_td:not(:first-child)[data-label]]:before:text-ink-3 @max-[480px]:[&_td:not(:first-child)[data-label]]:before:content-[attr(data-label)]')}>
+        {children}
+      </table>
+    </div>
+  ),
+};
+
+export const Prose = memo(function Prose({ children, size = 'base', stack = false, className }: {
+  children: string;
+  /** `sm` for a side panel, a comment or a quoted body. */
+  size?: 'base' | 'sm';
+  /** A table narrower than 480px reads as labelled cards, one per row. */
+  stack?: boolean;
+  className?: string;
+}) {
   return (
     <div className={cn('min-w-0 text-ink-2 break-words', size === 'base' ? 'text-base leading-[1.7]' : 'text-sm leading-relaxed', className)}>
-      <ReactMarkdown remarkPlugins={[remarkGfm]} urlTransform={safeMarkdownUrl} components={COMPONENTS}>
+      <ReactMarkdown remarkPlugins={[remarkGfm]} rehypePlugins={[labelCells]} urlTransform={safeMarkdownUrl} components={stack ? STACKED : COMPONENTS}>
         {children.replace(/\r\n/g, '\n').trim()}
       </ReactMarkdown>
     </div>

package/payload/src/components/patterns/prose/preview.tsx

@@ -40,6 +40,11 @@ const HOSTILE = `A reply pasted from somewhere else:
 
 ![A tracking pixel](https://elsewhere.example/pixel.png)`;
 
+const DECISIONS = `| Choice | Chosen | Rejected because |
+|---|---|---|
+| Queue | Postgres \`SKIP LOCKED\` | a broker is one more service to run for 40 jobs a minute |
+| Retries | Three, with backoff | a fourth retry has never succeeded in the last 90 days |`;
+
 export default function ProsePreview() {
   return (
     <>
@@ -58,6 +63,14 @@ export default function ProsePreview() {
           <div className="w-80 p-4"><Prose size="sm">{REVIEW.split('## What we are changing')[1]}</Prose></div>
         </Plane>
       </Specimen>
+      <Specimen label="Stacked" note="With stack, a table under 480px of its own width reads as one card per row: the first cell its title, each later cell under its column's heading. Wider, it is the same table." stack>
+        <Plane on="surface">
+          <div className="flex flex-wrap gap-6 p-4">
+            <div className="w-80"><Prose size="sm" stack>{DECISIONS}</Prose></div>
+            <div className="w-[560px] max-w-full"><Prose size="sm" stack>{DECISIONS}</Prose></div>
+          </div>
+        </Plane>
+      </Specimen>
     </>
   );
 }

package/payload/tests/prose-cell-labels.test.tsx

@@ -0,0 +1,31 @@
+import { render } from '@testing-library/react';
+import { describe, expect, test } from 'vitest';
+import { Prose } from '@/components/patterns/prose';
+
+const DOC = `| Choice | Chosen | Rejected because |
+|---|---|---|
+| Store | **Postgres** | the queue needs order |
+| Cache | none | |
+
+| A | \`B\` |
+|---|---|
+| 1 | 2 | 3 |`;
+
+describe('Prose names each body cell\'s column (#75)', () => {
+  test('writes the column heading on every body cell, per table, as plain text', () => {
+    const { container } = render(<Prose>{DOC}</Prose>);
+    const [first, second] = [...container.querySelectorAll('table')];
+    expect([...first.querySelectorAll('tbody td')].map((td) => td.getAttribute('data-label'))).toEqual(['Choice', 'Chosen', 'Rejected because', 'Choice', 'Chosen', 'Rejected because']);
+    expect([...second.querySelectorAll('tbody td')].map((td) => td.getAttribute('data-label'))).toEqual(['A', 'B']);
+    expect(container.querySelectorAll('th[data-label]')).toHaveLength(0);
+  });
+
+  test('stack makes each table\'s frame the container its rows stack in', () => {
+    const plain = render(<Prose>{DOC}</Prose>);
+    expect(plain.container.querySelector('.\\@container')).toBeNull();
+    plain.unmount();
+    const { container } = render(<Prose stack>{DOC}</Prose>);
+    expect(container.querySelectorAll('.\\@container > table')).toHaveLength(2);
+    expect(container.querySelector('tbody td')).toHaveAttribute('data-label', 'Choice');
+  });
+});