feat(react): redesign descriptions api

.changeset/smooth-llamas-tease.md

@@ -0,0 +1,5 @@
+---
+'@tiny-design/react': patch
+---
+
+Redesign the Descriptions component with a new data-driven API, responsive columns, semantic rendering modes, richer docs demos, and updated layout behavior.

packages/react/src/descriptions/__tests__/__snapshots__/descriptions.test.tsx.snap

@@ -3,49 +3,114 @@
 exports[`<Descriptions /> should match the snapshot 1`] = `
 <DocumentFragment>
   <div
-    class="ty-descriptions ty-descriptions_md"
+    class="ty-descriptions ty-descriptions_md ty-descriptions_horizontal ty-descriptions_list ty-descriptions_label-start ty-descriptions_content-start"
   >
+    <div
+      class="ty-descriptions__header"
+    >
+      <div
+        class="ty-descriptions__title"
+      >
+        Profile
+      </div>
+    </div>
     <div
       class="ty-descriptions__body"
     >
-      <table>
-        <tbody>
-          <tr
-            class="ty-descriptions__row"
+      <dl
+        class="ty-descriptions__list"
+        style="grid-template-columns: repeat(3, minmax(0, 1fr));"
+      >
+        <div
+          class="ty-descriptions__list-item"
+          style="grid-column: span 1;"
+        >
+          <dt
+            class="ty-descriptions__item-label"
           >
-            <td
-              class="ty-descriptions__item"
-              colspan="1"
+            <div
+              class="ty-descriptions__label-inner"
             >
               <span
-                class="ty-descriptions__item-label ty-descriptions__item_colon"
+                class="ty-descriptions__label-text"
               >
                 Name
               </span>
               <span
-                class="ty-descriptions__item-content"
+                class="ty-descriptions__separator"
               >
-                John
+                :
               </span>
-            </td>
-            <td
-              class="ty-descriptions__item"
-              colspan="2"
+            </div>
+          </dt>
+          <dd
+            class="ty-descriptions__item-content"
+          >
+            John
+          </dd>
+        </div>
+        <div
+          class="ty-descriptions__list-item"
+          style="grid-column: span 1;"
+        >
+          <dt
+            class="ty-descriptions__item-label"
+          >
+            <div
+              class="ty-descriptions__label-inner"
             >
               <span
-                class="ty-descriptions__item-label ty-descriptions__item_colon"
+                class="ty-descriptions__label-text"
               >
                 Age
               </span>
               <span
-                class="ty-descriptions__item-content"
+                class="ty-descriptions__separator"
+              >
+                :
+              </span>
+            </div>
+          </dt>
+          <dd
+            class="ty-descriptions__item-content"
+          >
+            30
+          </dd>
+        </div>
+        <div
+          class="ty-descriptions__list-item"
+          style="grid-column: span 1;"
+        >
+          <dt
+            class="ty-descriptions__item-label"
+          >
+            <div
+              class="ty-descriptions__label-inner"
+            >
+              <span
+                class="ty-descriptions__label-text"
+              >
+                Address
+              </span>
+              <span
+                class="ty-descriptions__separator"
               >
-                30
+                :
               </span>
-            </td>
-          </tr>
-        </tbody>
-      </table>
+            </div>
+          </dt>
+          <dd
+            class="ty-descriptions__item-content"
+          >
+            Sydney
+          </dd>
+        </div>
+      </dl>
+    </div>
+    <div
+      class="ty-descriptions__footer"
+    >
+      Footer
     </div>
   </div>
 </DocumentFragment>

packages/react/src/descriptions/__tests__/descriptions.test.tsx

@@ -5,9 +5,12 @@ import Descriptions from '../index';
 describe('<Descriptions />', () => {
   it('should match the snapshot', () => {
     const { asFragment } = render(
-      <Descriptions>
+      <Descriptions title="Profile" footer="Footer">
         <Descriptions.Item label="Name">John</Descriptions.Item>
         <Descriptions.Item label="Age">30</Descriptions.Item>
+        <Descriptions.Item label="Address" span="fill">
+          Sydney
+        </Descriptions.Item>
       </Descriptions>
     );
     expect(asFragment()).toMatchSnapshot();
@@ -20,15 +23,18 @@ describe('<Descriptions />', () => {
       </Descriptions>
     );
     expect(container.firstChild).toHaveClass('ty-descriptions');
+    expect(container.querySelector('dl')).toBeInTheDocument();
   });
 
-  it('should render title', () => {
+  it('should render header and footer', () => {
     const { getByText } = render(
-      <Descriptions title="User Info">
+      <Descriptions title="User Info" extra={<button>Action</button>} footer="Summary footer">
         <Descriptions.Item label="Name">John</Descriptions.Item>
       </Descriptions>
     );
     expect(getByText('User Info')).toBeInTheDocument();
+    expect(getByText('Action')).toBeInTheDocument();
+    expect(getByText('Summary footer')).toBeInTheDocument();
   });
 
   it('should render items', () => {
@@ -40,4 +46,34 @@ describe('<Descriptions />', () => {
     expect(getByText('Name')).toBeInTheDocument();
     expect(getByText('John')).toBeInTheDocument();
   });
+
+  it('should render items from items prop', () => {
+    const { getByText } = render(
+      <Descriptions
+        items={[
+          { key: 'name', label: 'Name', content: 'John' },
+          { key: 'role', label: 'Role', content: 'Maintainer' },
+        ]}
+      />
+    );
+
+    expect(getByText('Name')).toBeInTheDocument();
+    expect(getByText('Maintainer')).toBeInTheDocument();
+  });
+
+  it('should use table semantic when bordered', () => {
+    const { container } = render(
+      <Descriptions bordered items={[{ key: 'name', label: 'Name', content: 'John' }]} />
+    );
+
+    expect(container.querySelector('table')).toBeInTheDocument();
+  });
+
+  it('should render empty placeholder for nullish content', () => {
+    const { getByText } = render(
+      <Descriptions items={[{ key: 'name', label: 'Name', content: null }]} empty="Pending" />
+    );
+
+    expect(getByText('Pending')).toBeInTheDocument();
+  });
 });

packages/react/src/descriptions/demo/Basic.tsx

@@ -1,14 +1,22 @@
 import React from 'react';
-import { Descriptions } from '@tiny-design/react';
+import { Button, Descriptions, Tag } from '@tiny-design/react';
 
 export default function BasicDemo() {
   return (
-    <Descriptions title="User Info">
-      <Descriptions.Item label="UserName">React</Descriptions.Item>
-      <Descriptions.Item label="Telephone">0200004567</Descriptions.Item>
-      <Descriptions.Item label="Live">Sydney, Australia</Descriptions.Item>
-      <Descriptions.Item label="Remark">Great</Descriptions.Item>
-      <Descriptions.Item label="Address">456P+HW Camperdown, New South Wales</Descriptions.Item>
+    <Descriptions
+      title="Workspace Profile"
+      extra={<Button size="sm" type="primary">Edit</Button>}
+      columns={2}
+      footer={<span style={{ color: 'var(--ty-color-text-3)' }}>Last synced 2 minutes ago</span>}>
+      <Descriptions.Item label="Name">Tiny Studio</Descriptions.Item>
+      <Descriptions.Item label="Region">Australia Southeast</Descriptions.Item>
+      <Descriptions.Item label="Owner" extra={<Tag size="sm">Core</Tag>}>
+        Product Ops
+      </Descriptions.Item>
+      <Descriptions.Item label="Website">tiny.design</Descriptions.Item>
+      <Descriptions.Item label="Summary" span="fill">
+        Shared component workspace for tokens, docs, charts, and platform-specific UI packages.
+      </Descriptions.Item>
     </Descriptions>
   );
-}
+}

packages/react/src/descriptions/demo/Border.tsx

@@ -1,36 +1,40 @@
 import React from 'react';
-import { Descriptions, Badge } from '@tiny-design/react';
+import { Badge, Descriptions } from '@tiny-design/react';
 
 export default function BorderDemo() {
   return (
-    <Descriptions title="User Info" bordered>
-      <Descriptions.Item label="Product">Cloud Database</Descriptions.Item>
-      <Descriptions.Item label="Billing Mode">Prepaid</Descriptions.Item>
-      <Descriptions.Item label="Automatic Renewal">YES</Descriptions.Item>
-      <Descriptions.Item label="Order time">2018-04-24 18:00:00</Descriptions.Item>
-      <Descriptions.Item label="Usage Time" span={2}>
-        2019-04-24 18:00:00
-      </Descriptions.Item>
-      <Descriptions.Item label="Status" span={3}>
-        <Badge dot processing color="#1890ff" />
-        Running
-      </Descriptions.Item>
-      <Descriptions.Item label="Negotiated Amount">$80.00</Descriptions.Item>
-      <Descriptions.Item label="Discount">$20.00</Descriptions.Item>
-      <Descriptions.Item label="Official Receipts">$60.00</Descriptions.Item>
-      <Descriptions.Item label="Config Info">
-        Data disk type: MongoDB
-        <br />
-        Database version: 3.4
-        <br />
-        Package: dds.mongo.mid
-        <br />
-        Storage space: 10 GB
-        <br />
-        Replication factor: 3
-        <br />
-        Region: East China 1
-      </Descriptions.Item>
-    </Descriptions>
+    <Descriptions
+      title="Deployment Contract"
+      bordered
+      semantic="table"
+      columns={2}
+      items={[
+        { key: 'service', label: 'Service', content: 'Managed DB' },
+        { key: 'billing', label: 'Billing', content: 'Annual prepaid' },
+        { key: 'renewal', label: 'Renewal', content: 'Enabled' },
+        { key: 'orderedAt', label: 'Ordered', content: 'Apr 18, 10:30' },
+        { key: 'period', label: 'Usage Window', content: 'Apr 18, 2026 to Apr 18, 2027', span: 'fill' },
+        {
+          key: 'status',
+          label: 'Status',
+          content: (
+            <span style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}>
+              <Badge dot processing color="#1890ff" />
+              Running
+            </span>
+          ),
+          span: 'fill',
+        },
+        { key: 'amount', label: 'Amount', content: '$80.00' },
+        { key: 'discount', label: 'Discount', content: '$20.00' },
+        { key: 'total', label: 'Receipts', content: '$60.00' },
+        {
+          key: 'config',
+          label: 'Config',
+          span: 'fill',
+          content: 'MongoDB / 3 replicas / 10 GB',
+        },
+      ]}
+    />
   );
-}
+}

packages/react/src/descriptions/demo/EmptyHidden.tsx

@@ -0,0 +1,18 @@
+import React from 'react';
+import { Descriptions } from '@tiny-design/react';
+
+export default function EmptyHiddenDemo() {
+  return (
+    <Descriptions
+      title="Empty And Hidden"
+      columns={2}
+      empty="Not configured"
+      items={[
+        { key: 'env', label: 'Environment', content: 'Production' },
+        { key: 'token', label: 'Access Token', content: null },
+        { key: 'internal', label: 'Internal Note', content: 'Only for admins', hidden: true },
+        { key: 'fallback', label: 'Rollback Plan', content: undefined },
+      ]}
+    />
+  );
+}

packages/react/src/descriptions/demo/RenderAlign.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { Descriptions, Tag } from '@tiny-design/react';
+
+export default function RenderAlignDemo() {
+  return (
+    <Descriptions
+      title="Render And Align"
+      semantic="table"
+      bordered
+      columns={1}
+      labelAlign="end"
+      contentAlign="start"
+      items={[
+        { key: 'severity', label: 'Severity', content: 'High' },
+        { key: 'owner', label: 'Owner', content: 'UI Foundation' },
+        { key: 'eta', label: 'ETA', content: '2 days' },
+        { key: 'scope', label: 'Scope', content: 'Descriptions demo refinement' },
+      ]}
+      labelRender={(item) => (
+        <span style={{ display: 'inline-block', minWidth: 88, fontSize: 12, letterSpacing: '0.08em' }}>
+          {item.label}
+        </span>
+      )}
+      contentRender={(item) => {
+        if (item.key === 'severity') {
+          return <Tag color="warning">High</Tag>;
+        }
+
+        return item.content;
+      }}
+    />
+  );
+}