@scalewing/react 1.25.0 → 1.26.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @scalewing/react
 
+## 1.26.0
+
+### Minor Changes
+
+- e484799: `DescriptionList` and `DescriptionItem` (with `DescriptionListProps` and `DescriptionItemProps`): terms paired with what each says, one per row (`docs/requests/teisoro-description-list.md`, Teisoro F-006-S03).
+
+  - A `dl` of items, each a `div` grouping a `dt` (`term`) with its `dd` (`children`); the list and each item take their own HTML attributes and `className`.
+  - From `md` up the items share the list's two columns (`subgrid`): the term column as wide as the widest term, up to 40% of the list, then the detail. Every row aligns to its top, a hairline (`--sw-color-border`, `CanvasText` in forced colors) divides the rows, and the list is flush above its first row and below its last.
+  - Below `md` each term sits over its detail.
+  - A term and a detail are columns of lines: each child is its own line with its own line height, so a caption term starts level with a caption detail; each is as wide as its content unless it sets its own width (a `Progress` fills the detail), and long unbreakable words wrap. Wrap inline content in one element.
+  - New generated classes `sw-description-list`, `sw-description-item`, `sw-description-term` and `sw-description-detail`. No new tokens or dependencies.
+
 ## 1.25.0
 
 ### Minor Changes

package/README.md

@@ -22,6 +22,8 @@ import {
   Tooltip,
   InfoTip,
   Separator,
+  DescriptionList,
+  DescriptionItem,
   DenominationGrid,
   FilterChips,
   Grid,
@@ -310,6 +312,27 @@ A header `TableCell` (`as="th"`) with `sort` (`'ascending'`, `'descending'` or `
 
 `Separator` divides sections with a token-colored line. It is horizontal by default; use `orientation="vertical"` in a flex row. Set `decorative` when the line only supports layout so assistive technology ignores it.
 
+`DescriptionList` pairs terms with what each says, one `DescriptionItem` per row: a `dl` whose items each group a `dt` (`term`) with its `dd` (`children`). From `md` up the term sits in a start column as wide as the widest term, up to 40% of the list, and the detail beside it; every row aligns to its top, so a term and its detail's first line start level, and a hairline divides the rows, with no space above the first row or below the last. Below `md` each term sits over its detail. The list sets only the layout: pass your own `Text` for the term and the detail. Each child of a term or a detail is its own line with its own line height (a column), as wide as its content unless it sets its own width (a `Progress` fills the detail; a `Field` keeps its input's width): wrap inline content, such as words and a link on one line, in one element such as an `Inline`. Long unbreakable words wrap inside their column. A `dl` has no ARIA role, so name a list with a visible heading, and `aria-labelledby` on the `section` around it, rather than an `aria-label` on the list.
+
+```tsx
+<DescriptionList>
+  <DescriptionItem
+    term={
+      <Text variant="caption" color="muted">
+        Wetland
+      </Text>
+    }
+  >
+    <Inline align="start" gap={2} wrap>
+      <Text variant="data">12 herons</Text>
+      <Text variant="caption" color="muted">
+        Recounted
+      </Text>
+    </Inline>
+  </DescriptionItem>
+</DescriptionList>
+```
+
 `Card` defaults to `glass`; `outlined` and `elevated` are solid surfaces, and `filled` is a quiet `--sw-color-subtle` fill with no border for plain information apart from pressable rows.
 
 `--sw-color-accentSubtle` is the accent tint from `@scalewing/tokens`: a quiet fill behind accent text or glyphs that keeps 4.5:1. The stylesheet and every palette file set it, and a palette that moves the accent or surface retints it.

package/dist/components/DescriptionList.d.ts

@@ -0,0 +1,28 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export type DescriptionListProps = Omit<HTMLAttributes<HTMLDListElement>, 'children'> & {
+    /** The list's `DescriptionItem`s. */
+    children: ReactNode;
+};
+/**
+ * Terms and what each one says, one item per row: the term in a start
+ * column as wide as the widest term (up to 40% of the list), the detail
+ * beside it, a hairline between rows, every row aligned to its top. Below
+ * the layout breakpoint (`md`) each term sits over its detail.
+ */
+export declare function DescriptionList({ children, className, ...rest }: DescriptionListProps): import("react").JSX.Element;
+export type DescriptionItemProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    /**
+     * What the row describes, such as a name; the consumer's own `Text`. Each
+     * child of the term, and of the detail, is its own line.
+     */
+    term: ReactNode;
+    /**
+     * What the term says: text, a link, or several lines. Each child is its
+     * own line, as wide as its content unless it sets its own width (a
+     * `Progress` fills the detail); wrap words and a link that share a line
+     * in one element such as `Inline`.
+     */
+    children: ReactNode;
+};
+/** One row of a `DescriptionList`: a `dt` and its `dd` in one group. */
+export declare function DescriptionItem({ term, children, className, ...rest }: DescriptionItemProps): import("react").JSX.Element;

package/dist/components/DescriptionList.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '../class-names.js';
+/**
+ * Terms and what each one says, one item per row: the term in a start
+ * column as wide as the widest term (up to 40% of the list), the detail
+ * beside it, a hairline between rows, every row aligned to its top. Below
+ * the layout breakpoint (`md`) each term sits over its detail.
+ */
+export function DescriptionList({ children, className, ...rest }) {
+    return (_jsx("dl", { className: cx('sw-description-list', className), ...rest, children: children }));
+}
+/** One row of a `DescriptionList`: a `dt` and its `dd` in one group. */
+export function DescriptionItem({ term, children, className, ...rest }) {
+    return (_jsxs("div", { className: cx('sw-description-item', className), ...rest, children: [_jsx("dt", { className: "sw-description-term", children: term }), _jsx("dd", { className: "sw-description-detail", children: children })] }));
+}

package/dist/css/css-components.js

@@ -23,6 +23,7 @@ import { cssTooltipClasses } from './css-tooltip.js';
 import { cssInfoTipClasses } from './css-info-tip.js';
 import { cssSeparatorClasses } from './css-separator.js';
 import { cssStatTileClasses } from './css-stat-tile.js';
+import { cssDescriptionListClasses } from './css-description-list.js';
 import { cssTabsClasses } from './css-tabs.js';
 import { cssResponsiveClasses } from './css-responsive.js';
 import { cssFilterChipsClasses } from './css-filter-chips.js';
@@ -151,6 +152,8 @@ ${cssSeparatorClasses()}
 
 ${cssStatTileClasses()}
 
+${cssDescriptionListClasses()}
+
 ${cssTabsClasses()}
 
 ${cssFilterChipsClasses()}

package/dist/css/css-description-list.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The description list: a two-column grid whose items share its columns
+ * (`subgrid`), so every term starts the same column and every detail the
+ * next. The term column fits the widest term up to 40% of the list. A
+ * hairline divides the rows, the list sits flush with no space above the
+ * first row or below the last, and each row aligns to its top. Below `md`
+ * a term sits over its detail. A term and a detail are columns of lines:
+ * each child is its own line with its own line height, so a caption term
+ * starts level with a caption detail instead of on the list's taller line.
+ */
+export declare function cssDescriptionListClasses(): string;
+export declare function descriptionListClassCatalog(): string[];

package/dist/css/css-description-list.js

@@ -0,0 +1,63 @@
+import { breakpointQuery } from './breakpoints.js';
+/**
+ * The description list: a two-column grid whose items share its columns
+ * (`subgrid`), so every term starts the same column and every detail the
+ * next. The term column fits the widest term up to 40% of the list. A
+ * hairline divides the rows, the list sits flush with no space above the
+ * first row or below the last, and each row aligns to its top. Below `md`
+ * a term sits over its detail. A term and a detail are columns of lines:
+ * each child is its own line with its own line height, so a caption term
+ * starts level with a caption detail instead of on the list's taller line.
+ */
+export function cssDescriptionListClasses() {
+    return `.sw-description-list {
+  column-gap: var(--sw-space-4);
+  display: grid;
+  grid-template-columns: fit-content(40%) minmax(0, 1fr);
+  margin: 0;
+  min-width: 0;
+}
+
+.sw-description-item {
+  align-items: start;
+  display: grid;
+  grid-column: 1 / -1;
+  grid-template-columns: subgrid;
+  padding-block: var(--sw-space-2);
+  row-gap: var(--sw-space-1);
+}
+
+.sw-description-item:first-child { padding-top: 0; }
+
+.sw-description-item:last-child { padding-bottom: 0; }
+
+.sw-description-item + .sw-description-item {
+  border-top: 1px solid var(--sw-color-border);
+}
+
+.sw-description-term,
+.sw-description-detail {
+  align-items: flex-start;
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+@media ${breakpointQuery('below', 'md')} {
+  .sw-description-list { grid-template-columns: minmax(0, 1fr); }
+}
+
+@media (forced-colors: active) {
+  .sw-description-item + .sw-description-item { border-top-color: CanvasText; }
+}`;
+}
+export function descriptionListClassCatalog() {
+    return [
+        'sw-description-list',
+        'sw-description-item',
+        'sw-description-term',
+        'sw-description-detail',
+    ];
+}

package/dist/css/stylesheet.js

@@ -13,6 +13,7 @@ import { tooltipClassCatalog } from './css-tooltip.js';
 import { infoTipClassCatalog } from './css-info-tip.js';
 import { separatorClassCatalog } from './css-separator.js';
 import { statTileClassCatalog } from './css-stat-tile.js';
+import { descriptionListClassCatalog } from './css-description-list.js';
 import { tabsClassCatalog } from './css-tabs.js';
 import { responsiveClassCatalog } from './css-responsive.js';
 import { filterChipsClassCatalog } from './css-filter-chips.js';
@@ -76,6 +77,7 @@ export function utilityClassCatalog() {
         ...infoTipClassCatalog(),
         ...separatorClassCatalog(),
         ...statTileClassCatalog(),
+        ...descriptionListClassCatalog(),
         ...tabsClassCatalog(),
         ...filterChipsClassCatalog(),
         ...gridClassCatalog(),

package/dist/index.d.ts

@@ -42,6 +42,8 @@ export type { Breakpoint, BreakpointDirection, VisibilityBreakpoint, } from './c
 export { breakpointQuery } from './css/breakpoints.js';
 export { Separator } from './components/Separator.js';
 export type { SeparatorOrientation, SeparatorProps, } from './components/Separator.js';
+export { DescriptionItem, DescriptionList, } from './components/DescriptionList.js';
+export type { DescriptionItemProps, DescriptionListProps, } from './components/DescriptionList.js';
 export { Grid } from './components/Grid.js';
 export type { GridColumns, GridProps } from './components/Grid.js';
 export type { GridColumnSpan } from './css/css-grid-span.js';

package/dist/index.js

@@ -35,6 +35,7 @@ export { ThemeProvider, useTheme, } from './theme/ThemeProvider.js';
 export { utilityClassCatalog } from './css/stylesheet.js';
 export { breakpointQuery } from './css/breakpoints.js';
 export { Separator } from './components/Separator.js';
+export { DescriptionItem, DescriptionList, } from './components/DescriptionList.js';
 export { Grid } from './components/Grid.js';
 export { DenominationGrid } from './components/DenominationGrid.js';
 export { FilterChips } from './components/FilterChips.js';

package/dist/styles.css

@@ -3039,6 +3039,49 @@ body {
   .sw-stat-tile-primary { background: Highlight; }
 }
 
+.sw-description-list {
+  column-gap: var(--sw-space-4);
+  display: grid;
+  grid-template-columns: fit-content(40%) minmax(0, 1fr);
+  margin: 0;
+  min-width: 0;
+}
+
+.sw-description-item {
+  align-items: start;
+  display: grid;
+  grid-column: 1 / -1;
+  grid-template-columns: subgrid;
+  padding-block: var(--sw-space-2);
+  row-gap: var(--sw-space-1);
+}
+
+.sw-description-item:first-child { padding-top: 0; }
+
+.sw-description-item:last-child { padding-bottom: 0; }
+
+.sw-description-item + .sw-description-item {
+  border-top: 1px solid var(--sw-color-border);
+}
+
+.sw-description-term,
+.sw-description-detail {
+  align-items: flex-start;
+  display: flex;
+  flex-direction: column;
+  margin: 0;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+
+@media not all and (min-width: 48rem) {
+  .sw-description-list { grid-template-columns: minmax(0, 1fr); }
+}
+
+@media (forced-colors: active) {
+  .sw-description-item + .sw-description-item { border-top-color: CanvasText; }
+}
+
 .sw-tabs {
   border-bottom: 1px solid var(--sw-color-border);
   display: flex;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scalewing/react",
-  "version": "1.25.0",
+  "version": "1.26.0",
   "description": "Scalewing DOM components and package-owned CSS utilities.",
   "type": "module",
   "license": "MIT",