@kcascend/liquid-ui 0.0.5 → 0.0.6

package/README.md

@@ -1,66 +1,66 @@
-# Liquid UI Package
-
-`@kcascend/liquid-ui` is the reusable UI package for Liquid Design System consumers.
-
-## Local development
-
-1. Run `npm install` from the repository root to install the local file dependency.
-2. Run `npm run build:ui` to rebuild the package outputs in `packages/liquid-ui/dist`.
-3. Run `npm run storybook` to rebuild the package and launch Storybook against the package boundary.
-
-## Grid usage
-
-The package exposes a grid primitive through `GridLayout` and `GridColumn`, plus an approved layout catalog for application shells and content regions.
-
-```tsx
-import {
-  approvedContentLayoutPatterns,
-  GridColumn,
-  GridLayout,
-} from '@kcascend/liquid-ui';
-
-export function Example() {
-  const layout = approvedContentLayoutPatterns.sidebarEnd;
-
-  return (
-    <GridLayout as="div">
-      <GridColumn {...layout.regions.primary}>Primary</GridColumn>
-      <GridColumn {...layout.regions.secondary}>Secondary</GridColumn>
-    </GridLayout>
-  );
-}
-```
-
-Supported layout features:
-
-- Responsive spans through `sm`, `md`, `lg`, `xlg`, and `max`.
-- Offset columns with object values like `md={{ span: 4, offset: 2 }}`.
-- Gutter modes with `narrow` and `condensed`.
-- `withRowGap` to keep vertical spacing aligned with the active gutter.
-- `fullWidth` for viewport-spanning layouts.
-- `subgrid` for nested grids that inherit the parent column scaffold.
-- Auto columns when a `GridColumn` is rendered without explicit breakpoint props.
-
-Approved layout guidance:
-
-- Start application shells from `approvedShellRows`.
-- Start page content from `approvedContentLayoutPatterns`.
-- Introduce a bespoke breakpoint map only when a screen cannot be expressed by the approved patterns and that exception is documented in a spec.
-
-## Figma governance
-
-Every reusable component must record an approved Figma reference in story metadata or component documentation before it is considered ready for review. The initial workflow example in this package uses the Liquid token source in Figma
-
-Storybook now demonstrates both patterns:
-
-- a package-consumed button component with Figma and accessibility metadata
-- a token values reference story that reads directly from the generated `tokens` export
-
-## Accessibility verification
-
-Each component review must include:
-
-- Keyboard interaction expectations when the component is interactive.
-- Name, role, and state guidance for assistive technologies.
-- Color contrast and focus treatment verification.
-- Storybook documentation that explains any usage constraints needed to stay WCAG 2.1 aligned.
+# Liquid UI Package
+
+`@kcascend/liquid-ui` is the reusable UI package for Liquid Design System consumers.
+
+## Local development
+
+1. Run `npm install` from the repository root to install the local file dependency.
+2. Run `npm run build:ui` to rebuild the package outputs in `packages/liquid-ui/dist`.
+3. Run `npm run storybook` to rebuild the package and launch Storybook against the package boundary.
+
+## Grid usage
+
+The package exposes a grid primitive through `GridLayout` and `GridColumn`, plus an approved layout catalog for application shells and content regions.
+
+```tsx
+import {
+  approvedContentLayoutPatterns,
+  GridColumn,
+  GridLayout,
+} from '@kcascend/liquid-ui';
+
+export function Example() {
+  const layout = approvedContentLayoutPatterns.sidebarEnd;
+
+  return (
+    <GridLayout as="div">
+      <GridColumn {...layout.regions.primary}>Primary</GridColumn>
+      <GridColumn {...layout.regions.secondary}>Secondary</GridColumn>
+    </GridLayout>
+  );
+}
+```
+
+Supported layout features:
+
+- Responsive spans through `sm`, `md`, `lg`, `xlg`, and `max`.
+- Offset columns with object values like `md={{ span: 4, offset: 2 }}`.
+- Gutter modes with `narrow` and `condensed`.
+- `withRowGap` to keep vertical spacing aligned with the active gutter.
+- `fullWidth` for viewport-spanning layouts.
+- `subgrid` for nested grids that inherit the parent column scaffold.
+- Auto columns when a `GridColumn` is rendered without explicit breakpoint props.
+
+Approved layout guidance:
+
+- Start application shells from `approvedShellRows`.
+- Start page content from `approvedContentLayoutPatterns`.
+- Introduce a bespoke breakpoint map only when a screen cannot be expressed by the approved patterns and that exception is documented in a spec.
+
+## Figma governance
+
+Every reusable component must record an approved Figma reference in story metadata or component documentation before it is considered ready for review. The initial workflow example in this package uses the Liquid token source in Figma
+
+Storybook now demonstrates both patterns:
+
+- a package-consumed button component with Figma and accessibility metadata
+- a token values reference story that reads directly from the generated `tokens` export
+
+## Accessibility verification
+
+Each component review must include:
+
+- Keyboard interaction expectations when the component is interactive.
+- Name, role, and state guidance for assistive technologies.
+- Color contrast and focus treatment verification.
+- Storybook documentation that explains any usage constraints needed to stay WCAG 2.1 aligned.

package/dist/components/DataTable/DataTable.d.ts

@@ -1,3 +1,3 @@
-import type { DataTableProps } from '../../types';
+import type { DataTableProps } from "../../types";
 export declare function DataTable({ captionDescription, captionTitle, className, columns, onRowSelectChange, onSelectAllChange, rowCheckboxLabel, rows, selectable, selectAllLabel, style, ...props }: DataTableProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=DataTable.d.ts.map

package/dist/components/DataTable/DataTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DataTable.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/DataTable.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAMlD,wBAAgB,SAAS,CAAC,EACxB,kBAAmE,EACnE,YAA4B,EAC5B,SAAS,EACT,OAAO,EACP,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,IAAI,EACJ,UAAkB,EAClB,cAAkC,EAClC,KAAK,EACL,GAAG,KAAK,EACT,EAAE,cAAc,2CAgGhB"}
+{"version":3,"file":"DataTable.d.ts","sourceRoot":"","sources":["../../../src/components/DataTable/DataTable.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAMlD,wBAAgB,SAAS,CAAC,EACxB,kBAAmE,EACnE,YAA4B,EAC5B,SAAS,EACT,OAAO,EACP,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,IAAI,EACJ,UAAkB,EAClB,cAAkC,EAClC,KAAK,EACL,GAAG,KAAK,EACT,EAAE,cAAc,2CAkGhB"}

package/dist/components/DataTable/DataTable.js

@@ -1,20 +1,20 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Checkbox } from '../Checkbox/Checkbox';
+import { Checkbox } from "../Checkbox/Checkbox";
 function getClassName(className) {
-    return ['liquid-data-table', className].filter(Boolean).join(' ');
+    return ["liquid-data-table", className].filter(Boolean).join(" ");
 }
-export function DataTable({ captionDescription = 'Brief description of what the table contains', captionTitle = 'Table title', className, columns, onRowSelectChange, onSelectAllChange, rowCheckboxLabel, rows, selectable = false, selectAllLabel = 'Select all rows', style, ...props }) {
+export function DataTable({ captionDescription = "Brief description of what the table contains", captionTitle = "Table title", className, columns, onRowSelectChange, onSelectAllChange, rowCheckboxLabel, rows, selectable = false, selectAllLabel = "Select all rows", style, ...props }) {
     const selectableRows = rows.filter((row) => !row.selectionDisabled);
     const selectedCount = selectableRows.filter((row) => row.selected).length;
     const allSelected = selectableRows.length > 0 && selectedCount === selectableRows.length;
     const partiallySelected = selectedCount > 0 && !allSelected;
-    return (_jsxs("section", { ...props, className: getClassName(className), style: style, children: [_jsxs("header", { className: "liquid-data-table__header", children: [_jsx("h2", { className: "liquid-data-table__title", children: captionTitle }), _jsx("p", { className: "liquid-data-table__description", children: captionDescription })] }), _jsxs("table", { className: "liquid-data-table__table", children: [_jsx("thead", { children: _jsxs("tr", { className: "liquid-data-table__column-row", children: [selectable ? (_jsx("th", { className: "liquid-data-table__column-header liquid-data-table__checkbox-column", scope: "col", children: _jsx(Checkbox, { checked: allSelected, indeterminate: partiallySelected, label: selectAllLabel, hideLabel: true, onChange: (event) => {
-                                            onSelectAllChange?.(event.currentTarget.checked);
-                                        } }) })) : null, columns.map((column) => (_jsx("th", { className: "liquid-data-table__column-header", "data-align": column.align ?? 'left', scope: "col", children: column.header }, column.id)))] }) }), _jsx("tbody", { children: rows.map((row, rowIndex) => {
-                            const resolvedId = row.id ?? rowIndex;
-                            return (_jsxs("tr", { className: "liquid-data-table__row", "data-selected": row.selected || undefined, children: [selectable ? (_jsx("td", { className: "liquid-data-table__cell liquid-data-table__checkbox-column", children: _jsx(Checkbox, { checked: Boolean(row.selected), disabled: row.selectionDisabled, hideLabel: true, label: rowCheckboxLabel?.(row, rowIndex) ??
-                                                `Select row ${rowIndex + 1}`, onChange: (event) => {
-                                                onRowSelectChange?.(resolvedId, event.currentTarget.checked);
-                                            } }) })) : null, columns.map((column, columnIndex) => (_jsx("td", { className: "liquid-data-table__cell", "data-align": column.align ?? 'left', children: row.cells[columnIndex] ?? null }, `${String(resolvedId)}:${column.id}`)))] }, String(resolvedId)));
-                        }) })] })] }));
+    return (_jsxs("section", { ...props, className: getClassName(className), style: style, children: [_jsxs("header", { className: "liquid-data-table__header", children: [_jsx("h2", { className: "liquid-data-table__title", children: captionTitle }), _jsx("p", { className: "liquid-data-table__description", children: captionDescription })] }), _jsx("div", { className: "liquid-data-table__scroll-container", children: _jsxs("table", { className: "liquid-data-table__table", children: [_jsx("thead", { children: _jsxs("tr", { className: "liquid-data-table__column-row", children: [selectable ? (_jsx("th", { className: "liquid-data-table__column-header liquid-data-table__checkbox-column", scope: "col", children: _jsx(Checkbox, { checked: allSelected, indeterminate: partiallySelected, label: selectAllLabel, hideLabel: true, onChange: (event) => {
+                                                onSelectAllChange?.(event.currentTarget.checked);
+                                            } }) })) : null, columns.map((column) => (_jsx("th", { className: "liquid-data-table__column-header", "data-align": column.align ?? "left", scope: "col", children: column.header }, column.id)))] }) }), _jsx("tbody", { children: rows.map((row, rowIndex) => {
+                                const resolvedId = row.id ?? rowIndex;
+                                return (_jsxs("tr", { className: "liquid-data-table__row", "data-selected": row.selected || undefined, children: [selectable ? (_jsx("td", { className: "liquid-data-table__cell liquid-data-table__checkbox-column", children: _jsx(Checkbox, { checked: Boolean(row.selected), disabled: row.selectionDisabled, hideLabel: true, label: rowCheckboxLabel?.(row, rowIndex) ??
+                                                    `Select row ${rowIndex + 1}`, onChange: (event) => {
+                                                    onRowSelectChange?.(resolvedId, event.currentTarget.checked);
+                                                } }) })) : null, columns.map((column, columnIndex) => (_jsx("td", { className: "liquid-data-table__cell", "data-align": column.align ?? "left", children: row.cells[columnIndex] ?? null }, `${String(resolvedId)}:${column.id}`)))] }, String(resolvedId)));
+                            }) })] }) })] }));
 }

package/dist/components/GridLayout/layoutPatterns.d.ts

@@ -1,5 +1,8 @@
-import type { GridColumnProps, ApprovedContentLayoutPattern, ApprovedShellRowConfig } from '../../types';
+import type { ApprovedLegacyContentLayoutPatternName, CanonicalLayoutPattern, CanonicalLayoutPatternName, GridColumnProps, ApprovedContentLayoutPattern, ApprovedShellRowConfig } from '../../types';
 export declare const approvedShellRows: Record<'header' | 'search' | 'results' | 'footer', ApprovedShellRowConfig>;
-export declare const approvedContentLayoutPatterns: Record<'single' | 'sidebarStart' | 'sidebarEnd' | 'splitEqual', ApprovedContentLayoutPattern>;
+export declare const approvedContentLayoutPatterns: Record<ApprovedLegacyContentLayoutPatternName, ApprovedContentLayoutPattern>;
+export declare const canonicalModernizationLayoutPatterns: Record<CanonicalLayoutPatternName, CanonicalLayoutPattern>;
+export declare const legacyToCanonicalLayoutPatternMap: Record<ApprovedLegacyContentLayoutPatternName, CanonicalLayoutPatternName[]>;
+export declare function getCanonicalModernizationLayoutPattern(patternName: CanonicalLayoutPatternName): CanonicalLayoutPattern;
 export declare function getApprovedContentLayoutColumns(patternName: keyof typeof approvedContentLayoutPatterns): Record<'primary' | 'secondary' | 'tertiary', GridColumnProps | undefined>;
 //# sourceMappingURL=layoutPatterns.d.ts.map

package/dist/components/GridLayout/layoutPatterns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"layoutPatterns.d.ts","sourceRoot":"","sources":["../../../src/components/GridLayout/layoutPatterns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAGf,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAoBrB,eAAO,MAAM,iBAAiB,EAAE,MAAM,CACpC,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,EAC1C,sBAAsB,CAqBvB,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAChD,QAAQ,GAAG,cAAc,GAAG,YAAY,GAAG,YAAY,EACvD,4BAA4B,CA0D7B,CAAC;AAEF,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,MAAM,OAAO,6BAA6B,GACtD,MAAM,CAAC,SAAS,GAAG,WAAW,GAAG,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAY3E"}
+{"version":3,"file":"layoutPatterns.d.ts","sourceRoot":"","sources":["../../../src/components/GridLayout/layoutPatterns.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sCAAsC,EACtC,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,EAGf,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,aAAa,CAAC;AAoBrB,eAAO,MAAM,iBAAiB,EAAE,MAAM,CACpC,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,EAC1C,sBAAsB,CAqBvB,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,MAAM,CAChD,sCAAsC,EACtC,4BAA4B,CA0D7B,CAAC;AAEF,eAAO,MAAM,oCAAoC,EAAE,MAAM,CACvD,0BAA0B,EAC1B,sBAAsB,CAoOvB,CAAC;AAEF,eAAO,MAAM,iCAAiC,EAAE,MAAM,CACpD,sCAAsC,EACtC,0BAA0B,EAAE,CAW7B,CAAC;AAEF,wBAAgB,sCAAsC,CACpD,WAAW,EAAE,0BAA0B,GACtC,sBAAsB,CAExB;AAED,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,MAAM,OAAO,6BAA6B,GACtD,MAAM,CAAC,SAAS,GAAG,WAAW,GAAG,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAY3E"}

package/dist/components/GridLayout/layoutPatterns.js

@@ -76,6 +76,233 @@ export const approvedContentLayoutPatterns = {
         },
     },
 };
+export const canonicalModernizationLayoutPatterns = {
+    'single-column-task-flow': {
+        description: 'Single readable task flow where users complete one primary progression of work.',
+        bestFit: 'Forms, guided tasks, and simple detail experiences.',
+        avoidWhen: 'Dense side-by-side comparison or persistent tool panels are required.',
+        geometryMode: 'wide',
+        regions: [
+            {
+                label: 'primary-task-column',
+                spans: {
+                    sm: '1-4',
+                    md: '1-6',
+                    lg: '1-8',
+                    xlg: 'span-controlled',
+                    max: 'span-controlled',
+                },
+            },
+        ],
+        adaptiveBehaviors: ['stack'],
+        scrollOwner: 'page',
+        runtimeValidationNotes: [
+            'Meet reflow requirements at 320 CSS px with one-dimensional page scrolling.',
+            'Keep DOM and focus order aligned with task order across breakpoints.',
+        ],
+        legacyCompatiblePatterns: ['single'],
+    },
+    'content-plus-aside': {
+        description: 'Primary content with a supporting aside that does not outrank the primary task.',
+        bestFit: 'Main workflow plus metadata, summary, or contextual help.',
+        avoidWhen: 'Users must complete aside content before understanding the primary task.',
+        geometryMode: 'wide',
+        regions: [
+            {
+                label: 'primary',
+                spans: { sm: 'full', md: '1-5', lg: '1-10', xlg: '1-10', max: '1-10' },
+            },
+            {
+                label: 'aside',
+                spans: {
+                    sm: 'stack-below',
+                    md: '6-8',
+                    lg: '11-16',
+                    xlg: '11-16',
+                    max: '11-16',
+                },
+            },
+        ],
+        adaptiveBehaviors: ['stack'],
+        scrollOwner: 'page',
+        runtimeValidationNotes: [
+            'Ensure focus order matches reading order when the aside stacks on smaller screens.',
+            'Do not trap keyboard users in supporting panes.',
+        ],
+        legacyCompatiblePatterns: ['sidebarEnd'],
+    },
+    'search-results-index': {
+        description: 'Search and browse index where results remain the primary region across breakpoints.',
+        bestFit: 'Directories and filtered collections without persistent detail panes.',
+        avoidWhen: 'Selected record detail must remain persistently visible with the list.',
+        geometryMode: 'wide',
+        regions: [
+            {
+                label: 'filters',
+                spans: {
+                    sm: 'disclosure',
+                    md: 'disclosure',
+                    lg: '1-4',
+                    xlg: '1-4',
+                    max: '1-4',
+                },
+            },
+            {
+                label: 'results',
+                spans: { sm: 'full', md: 'full', lg: '5-16', xlg: '5-16', max: '5-16' },
+            },
+        ],
+        adaptiveBehaviors: ['disclosure', 'stack'],
+        scrollOwner: 'named-region',
+        runtimeValidationNotes: [
+            'Only the labeled data/table region may own horizontal overflow.',
+            'Retain result count, pagination, and empty state semantics at all breakpoints.',
+        ],
+        legacyCompatiblePatterns: ['sidebarStart'],
+    },
+    'list-detail': {
+        description: 'Two-region list and selected-detail workflow with drill-in behavior on smaller screens.',
+        bestFit: 'Cases, records, and scan-then-inspect workflows.',
+        avoidWhen: 'Content groups are unrelated or many details must be compared at once.',
+        geometryMode: 'narrow',
+        regions: [
+            {
+                label: 'list',
+                spans: {
+                    sm: 'list-first',
+                    md: '1-3',
+                    lg: '1-5',
+                    xlg: '1-5',
+                    max: '1-5',
+                },
+            },
+            {
+                label: 'detail',
+                spans: {
+                    sm: 'after-selection',
+                    md: '4-8',
+                    lg: '6-16',
+                    xlg: '6-16',
+                    max: '6-16',
+                },
+            },
+        ],
+        adaptiveBehaviors: ['drill-in', 'stack'],
+        scrollOwner: 'page',
+        runtimeValidationNotes: [
+            'Preserve selection state and return orientation when switching between list and detail.',
+            'Ensure truncated list labels expose full text through accessible naming.',
+        ],
+        legacyCompatiblePatterns: ['sidebarStart', 'sidebarEnd'],
+    },
+    'dashboard-overview': {
+        description: 'Comparison-first operational overview with status tiles and queue snapshots.',
+        bestFit: 'Status cards, metrics, and operational queue overviews.',
+        avoidWhen: 'Long-form instructional reading is the dominant task.',
+        geometryMode: 'condensed',
+        regions: [
+            {
+                label: 'tile-grid',
+                spans: {
+                    sm: 'stack-priority-order',
+                    md: '2-up',
+                    lg: 'nested-condensed',
+                    xlg: 'nested-condensed',
+                    max: 'nested-condensed',
+                },
+            },
+        ],
+        adaptiveBehaviors: ['stack'],
+        scrollOwner: 'page',
+        runtimeValidationNotes: [
+            'Do not rely on position or color alone to convey tile state.',
+            'Keep text from hanging into condensed 1px gutters.',
+        ],
+        legacyCompatiblePatterns: ['splitEqual'],
+    },
+    'high-density-workspace': {
+        description: 'Dense operational workspace with controls and a separately scrollable data region.',
+        bestFit: 'Data tables, filters, and bulk-action workflows.',
+        avoidWhen: 'Public-facing workflows prioritize comprehension over operator density.',
+        geometryMode: 'condensed',
+        regions: [
+            {
+                label: 'controls-wrapper',
+                spans: {
+                    sm: 'full',
+                    md: 'full',
+                    lg: 'wide-wrapper',
+                    xlg: 'wide-wrapper',
+                    max: 'wide-wrapper',
+                },
+            },
+            {
+                label: 'dense-data-region',
+                spans: {
+                    sm: 'local-overflow-region',
+                    md: 'full',
+                    lg: 'nested-condensed',
+                    xlg: 'nested-condensed',
+                    max: 'nested-condensed',
+                },
+            },
+        ],
+        adaptiveBehaviors: ['stack', 'resize'],
+        scrollOwner: 'named-region',
+        runtimeValidationNotes: [
+            'Horizontal overflow must be constrained to the labeled data region only.',
+            'Keep controls before the data region for keyboard traversal.',
+        ],
+        legacyCompatiblePatterns: ['sidebarStart', 'splitEqual'],
+    },
+    'shell-influenced-layout': {
+        description: 'Main page layout that reflows within persistent shell chrome contexts.',
+        bestFit: 'Apps with persistent header, left navigation, and optional utility panels.',
+        avoidWhen: 'Shell chrome is treated as page content or IA labels change on collapse.',
+        geometryMode: 'wide',
+        regions: [
+            {
+                label: 'shell-chrome',
+                spans: {
+                    sm: 'header-trigger-nav',
+                    md: 'compact-rail',
+                    lg: 'expanded-nav',
+                },
+            },
+            {
+                label: 'content-grid',
+                spans: {
+                    sm: 'responsive',
+                    md: 'responsive',
+                    lg: 'responsive',
+                    xlg: 'responsive',
+                    max: 'responsive',
+                },
+            },
+        ],
+        adaptiveBehaviors: ['overlay', 'push', 'resize'],
+        scrollOwner: 'page',
+        runtimeValidationNotes: [
+            'Keep skip links and route meaning stable as shell panels open and close.',
+            'Treat panel dimensions as provisional until component contracts are finalized.',
+        ],
+        legacyCompatiblePatterns: ['single', 'sidebarStart', 'sidebarEnd'],
+    },
+};
+export const legacyToCanonicalLayoutPatternMap = {
+    single: ['single-column-task-flow', 'shell-influenced-layout'],
+    sidebarStart: [
+        'search-results-index',
+        'list-detail',
+        'high-density-workspace',
+        'shell-influenced-layout',
+    ],
+    sidebarEnd: ['content-plus-aside', 'list-detail', 'shell-influenced-layout'],
+    splitEqual: ['dashboard-overview', 'high-density-workspace'],
+};
+export function getCanonicalModernizationLayoutPattern(patternName) {
+    return canonicalModernizationLayoutPatterns[patternName];
+}
 export function getApprovedContentLayoutColumns(patternName) {
     const pattern = approvedContentLayoutPatterns[patternName];
     return {

package/dist/components/HeaderShell/HeaderShell.d.ts

@@ -1,3 +1,3 @@
-import type { HeaderShellProps } from '../../types';
+import type { HeaderShellProps } from "../../types";
 export declare function HeaderShell({ activeNavigationItemId, actions, brand, className, defaultActiveNavigationItemId, menuTriggerLabel, navigationItems, navLabel, onAction, onMenuTriggerClick, onNavigationChange, showMenuTrigger, style, ...props }: HeaderShellProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=HeaderShell.d.ts.map

package/dist/components/HeaderShell/HeaderShell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HeaderShell.d.ts","sourceRoot":"","sources":["../../../src/components/HeaderShell/HeaderShell.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,aAAa,CAAC;AA+GrB,wBAAgB,WAAW,CAAC,EAC1B,sBAAsB,EACtB,OAAO,EACP,KAAK,EACL,SAAS,EACT,6BAA6B,EAC7B,gBAA8B,EAC9B,eAAe,EACf,QAAoB,EACpB,QAAQ,EACR,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,KAAK,EACL,GAAG,KAAK,EACT,EAAE,gBAAgB,2CAiIlB"}
+{"version":3,"file":"HeaderShell.d.ts","sourceRoot":"","sources":["../../../src/components/HeaderShell/HeaderShell.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,gBAAgB,EAGjB,MAAM,aAAa,CAAC;AA2HrB,wBAAgB,WAAW,CAAC,EAC1B,sBAAsB,EACtB,OAAO,EACP,KAAK,EACL,SAAS,EACT,6BAA6B,EAC7B,gBAA8B,EAC9B,eAAe,EACf,QAAoB,EACpB,QAAQ,EACR,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,KAAK,EACL,GAAG,KAAK,EACT,EAAE,gBAAgB,2CAgMlB"}

package/dist/components/HeaderShell/HeaderShell.js

@@ -1,8 +1,8 @@
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useId, useMemo, useState } from 'react';
-import { Icon } from '../Icon/Icon';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useState } from "react";
+import { Icon } from "../Icon/Icon";
 function getClassName(className) {
-    return ['liquid-header-shell', className].filter(Boolean).join(' ');
+    return ["liquid-header-shell", className].filter(Boolean).join(" ");
 }
 function getFirstEnabledNavigationItem(items) {
     return items?.find((item) => !item.disabled)?.id;
@@ -10,61 +10,90 @@ function getFirstEnabledNavigationItem(items) {
 function HeaderNavigationLink({ activeItemId, item, onSelect, }) {
     const isSelected = item.id === activeItemId;
     if (item.href) {
-        return (_jsx("a", { className: "liquid-header-shell__nav-link", "data-selected": isSelected ? 'true' : undefined, href: item.href, onClick: (event) => {
+        return (_jsx("a", { className: "liquid-header-shell__nav-link", "data-selected": isSelected ? "true" : undefined, href: item.href, onClick: (event) => {
                 if (item.disabled) {
                     event.preventDefault();
                     return;
                 }
                 onSelect(item);
-            }, "aria-current": isSelected ? 'page' : undefined, "aria-disabled": item.disabled ? true : undefined, children: item.label }));
+            }, "aria-current": isSelected ? "page" : undefined, "aria-disabled": item.disabled ? true : undefined, children: item.label }));
     }
-    return (_jsx("button", { className: "liquid-header-shell__nav-link", "data-selected": isSelected ? 'true' : undefined, disabled: item.disabled, onClick: () => {
+    return (_jsx("button", { className: "liquid-header-shell__nav-link", "data-selected": isSelected ? "true" : undefined, disabled: item.disabled, onClick: () => {
             if (!item.disabled) {
                 onSelect(item);
             }
-        }, type: "button", "aria-current": isSelected ? 'page' : undefined, children: item.label }));
+        }, type: "button", "aria-current": isSelected ? "page" : undefined, children: item.label }));
 }
-function HeaderUtilityAction({ action, onAction, }) {
+function HeaderUtilityAction({ action, showLabel = false, onAction, }) {
     const icon = _jsx(Icon, { name: action.icon, size: action.iconSize ?? 20 });
     if (action.href) {
-        return (_jsx("a", { "aria-label": action.label, className: "liquid-header-shell__action", href: action.href, onClick: (event) => {
+        return (_jsxs("a", { "aria-label": action.label, className: "liquid-header-shell__action", href: action.href, onClick: (event) => {
                 if (action.disabled) {
                     event.preventDefault();
                     return;
                 }
                 onAction(action);
-            }, "aria-disabled": action.disabled ? true : undefined, children: icon }));
+            }, "aria-disabled": action.disabled ? true : undefined, children: [icon, showLabel ? (_jsx("span", { className: "liquid-header-shell__action-label", children: action.label })) : null] }));
     }
-    return (_jsx("button", { "aria-label": action.label, className: "liquid-header-shell__action", disabled: action.disabled, onClick: () => {
+    return (_jsxs("button", { "aria-label": action.label, className: "liquid-header-shell__action", disabled: action.disabled, onClick: () => {
             if (!action.disabled) {
                 onAction(action);
             }
-        }, type: "button", children: icon }));
+        }, type: "button", children: [icon, showLabel ? (_jsx("span", { className: "liquid-header-shell__action-label", children: action.label })) : null] }));
 }
-export function HeaderShell({ activeNavigationItemId, actions, brand, className, defaultActiveNavigationItemId, menuTriggerLabel = 'Open menu', navigationItems, navLabel = 'Primary', onAction, onMenuTriggerClick, onNavigationChange, showMenuTrigger, style, ...props }) {
+export function HeaderShell({ activeNavigationItemId, actions, brand, className, defaultActiveNavigationItemId, menuTriggerLabel = "Open menu", navigationItems, navLabel = "Primary", onAction, onMenuTriggerClick, onNavigationChange, showMenuTrigger, style, ...props }) {
     const fallbackActiveId = useMemo(() => getFirstEnabledNavigationItem(navigationItems), [navigationItems]);
     const [internalActiveId, setInternalActiveId] = useState(defaultActiveNavigationItemId ?? fallbackActiveId);
     const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
     const mobileAccordionId = useId();
     const shouldShowMenuTrigger = showMenuTrigger ?? true;
     const resolvedActiveId = activeNavigationItemId ?? internalActiveId ?? fallbackActiveId;
+    const closeMobileMenu = () => {
+        setIsMobileMenuOpen(false);
+    };
     const handleNavigationSelect = (item) => {
         if (activeNavigationItemId === undefined) {
             setInternalActiveId(item.id);
         }
         onNavigationChange?.(item.id, item);
-        setIsMobileMenuOpen(false);
+        closeMobileMenu();
     };
     const handleAction = (action) => {
         onAction?.(action.id, action);
         action.onClick?.();
-        setIsMobileMenuOpen(false);
+        closeMobileMenu();
     };
     const handleMenuTriggerClick = () => {
         setIsMobileMenuOpen((current) => !current);
         onMenuTriggerClick?.();
     };
+    useEffect(() => {
+        if (!isMobileMenuOpen) {
+            return;
+        }
+        const handleEscape = (event) => {
+            if (event.key === "Escape") {
+                closeMobileMenu();
+            }
+        };
+        const previousOverflow = document.body.style.overflow;
+        document.body.style.overflow = "hidden";
+        window.addEventListener("keydown", handleEscape);
+        return () => {
+            document.body.style.overflow = previousOverflow;
+            window.removeEventListener("keydown", handleEscape);
+        };
+    }, [isMobileMenuOpen]);
     const navigationContent = (_jsx(_Fragment, { children: navigationItems.map((item) => (_jsx(HeaderNavigationLink, { activeItemId: resolvedActiveId, item: item, onSelect: handleNavigationSelect }, item.id))) }));
     const actionsContent = actions?.length ? (_jsx(_Fragment, { children: actions.map((action) => (_jsx(HeaderUtilityAction, { action: action, onAction: handleAction }, action.id))) })) : null;
-    return (_jsxs("header", { ...props, className: getClassName(className), "data-mobile-menu-enabled": shouldShowMenuTrigger ? 'true' : undefined, style: style, children: [_jsxs("div", { className: "liquid-header-shell__inner", children: [_jsxs("div", { className: "liquid-header-shell__left", children: [shouldShowMenuTrigger ? (_jsx("button", { "aria-label": menuTriggerLabel, "aria-controls": mobileAccordionId, "aria-expanded": isMobileMenuOpen, className: "liquid-header-shell__action liquid-header-shell__menu-trigger", onClick: handleMenuTriggerClick, type: "button", children: _jsx(Icon, { name: "menu", size: 20 }) })) : null, _jsx("div", { className: "liquid-header-shell__brand", children: brand }), _jsx("nav", { "aria-label": navLabel, className: "liquid-header-shell__nav", children: _jsx("div", { className: "liquid-header-shell__nav-list", children: navigationContent }) })] }), actionsContent ? (_jsx("div", { className: "liquid-header-shell__actions", children: actionsContent })) : null, shouldShowMenuTrigger ? (_jsx("div", { "aria-hidden": "true", className: "liquid-header-shell__right-spacer" })) : null] }), shouldShowMenuTrigger ? (_jsxs("div", { className: "liquid-header-shell__mobile-accordion", hidden: !isMobileMenuOpen, id: mobileAccordionId, role: "region", children: [_jsx("nav", { "aria-label": navLabel, className: "liquid-header-shell__mobile-nav", children: _jsx("div", { className: "liquid-header-shell__mobile-nav-list", children: navigationContent }) }), actionsContent ? (_jsx("div", { className: "liquid-header-shell__mobile-actions", children: actionsContent })) : null] })) : null] }));
+    const mobileActionsContent = actions?.length ? (_jsx(_Fragment, { children: actions.map((action) => (_jsx(HeaderUtilityAction, { action: action, showLabel: true, onAction: handleAction }, `mobile:${action.id}`))) })) : null;
+    return (_jsxs("header", { ...props, className: getClassName(className), "data-mobile-menu-enabled": shouldShowMenuTrigger ? "true" : undefined, style: style, children: [_jsxs("div", { className: "liquid-header-shell__inner", children: [_jsxs("div", { className: "liquid-header-shell__left", children: [shouldShowMenuTrigger ? (_jsx("button", { "aria-label": menuTriggerLabel, "aria-controls": mobileAccordionId, "aria-expanded": isMobileMenuOpen, className: "liquid-header-shell__action liquid-header-shell__menu-trigger", onClick: handleMenuTriggerClick, type: "button", children: _jsx(Icon, { name: isMobileMenuOpen ? "close" : "menu", size: 20 }) })) : null, _jsx("div", { className: "liquid-header-shell__brand", children: brand }), _jsx("nav", { "aria-label": navLabel, className: "liquid-header-shell__nav", children: _jsx("div", { className: "liquid-header-shell__nav-list", children: navigationContent }) })] }), actionsContent ? (_jsx("div", { className: "liquid-header-shell__actions", children: actionsContent })) : null, shouldShowMenuTrigger ? (_jsx("div", { "aria-hidden": "true", className: "liquid-header-shell__right-spacer" })) : null] }), shouldShowMenuTrigger ? (_jsxs("div", { className: "liquid-header-shell__mobile-layer", "data-open": isMobileMenuOpen ? "true" : undefined, hidden: !isMobileMenuOpen, children: [_jsx("button", { "aria-label": "Close menu", className: "liquid-header-shell__mobile-backdrop", onClick: () => {
+                            closeMobileMenu();
+                        }, type: "button" }), _jsxs("aside", { className: "liquid-header-shell__mobile-panel", id: mobileAccordionId, role: "dialog", "aria-modal": "true", "aria-label": navLabel, onClick: (event) => {
+                            const target = event.target;
+                            if (target.closest(".liquid-header-shell__nav-link") ||
+                                target.closest(".liquid-header-shell__action")) {
+                                closeMobileMenu();
+                            }
+                        }, children: [_jsx("nav", { "aria-label": navLabel, className: "liquid-header-shell__mobile-nav", children: _jsx("div", { className: "liquid-header-shell__mobile-nav-list", children: navigationContent }) }), mobileActionsContent ? (_jsx("div", { className: "liquid-header-shell__mobile-actions", children: mobileActionsContent })) : null] })] })) : null] }));
 }

package/dist/governance/gridLayoutGovernance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gridLayoutGovernance.d.ts","sourceRoot":"","sources":["../../src/governance/gridLayoutGovernance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,eAAO,MAAM,oBAAoB,EAAE,mBASlC,CAAC"}
+{"version":3,"file":"gridLayoutGovernance.d.ts","sourceRoot":"","sources":["../../src/governance/gridLayoutGovernance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAEpD,eAAO,MAAM,oBAAoB,EAAE,mBAUlC,CAAC"}

package/dist/governance/gridLayoutGovernance.js

@@ -1,9 +1,10 @@
 export const gridLayoutGovernance = {
-    figmaUrl: 'https://www.figma.com/design/a9SMb2IjyRedfsaUMGXIyP/Liquid-DS---01-Components?node-id=1597-3&m=dev',
-    figmaNodeId: '1597:3',
+    figmaUrl: 'https://www.figma.com/design/a9SMb2IjyRedfsaUMGXIyP/Liquid-DS---01-Components?node-id=1764-4&m=dev',
+    figmaNodeId: '1764:4',
     accessibilityNotes: [
-        'Treat the layout examples as reference-only visuals and avoid using color alone to communicate meaning.',
-        'Ensure comparison regions remain readable on narrow viewports by allowing horizontal scroll where needed.',
-        'Preserve heading hierarchy so screen readers can navigate breakpoint, gutter mode, and row rhythm sections.',
+        'Treat layout examples as reference-only intent; validate runtime behavior in code for focus order, keyboard interaction, zoom, reflow, and localization.',
+        'Use geometry terminology consistently: Wide = 32px gutters, Narrow = 16px gutters, and Condensed = 1px gutters.',
+        'Do not allow page-level horizontal overflow; constrain horizontal scrolling to labeled data regions only when required.',
+        'Preserve DOM, reading, and task order alignment when layouts stack, drill in, or disclose at smaller breakpoints.',
     ],
 };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export { DataTable } from './components/DataTable/DataTable';
 export { DescriptionList } from './components/DescriptionList/DescriptionList';
 export { Form, FormItem, FormRow } from './components/Form/Form';
 export { GridColumn, GridLayout } from './components/GridLayout/GridLayout';
-export { approvedContentLayoutPatterns, approvedShellRows, getApprovedContentLayoutColumns, } from './components/GridLayout/layoutPatterns';
+export { approvedContentLayoutPatterns, approvedShellRows, canonicalModernizationLayoutPatterns, getApprovedContentLayoutColumns, getCanonicalModernizationLayoutPattern, legacyToCanonicalLayoutPatternMap, } from './components/GridLayout/layoutPatterns';
 export { HeaderShell } from './components/HeaderShell/HeaderShell';
 export { Icon, iconNames } from './components/Icon/Icon';
 export { Index } from './components/Index/Index';
@@ -54,6 +54,6 @@ export { tooltipGovernance } from './governance/tooltipGovernance';
 export { toggleInputGovernance } from './governance/toggleInputGovernance';
 export { tokens } from './generated/tokens';
 export type { Tokens } from './generated/tokens';
-export type { AccordionItem, AccordionProps, BreadcrumbItem, BreadcrumbProps, ButtonProps, ButtonSize, ButtonVariant, CardDetailItem, CardProps, CheckboxGroupProps, CheckboxProps, ContainedListItem, ContainedListProps, ContainedListVariant, DataTableCellAlignment, DataTableColumn, DataTableProps, DataTableRow, DescriptionListItem, DescriptionListProps, FormItemProps, FormProps, FormRowProps, GridBreakpoint, GridColumnProps, GridColumnSpan, GridColumnValue, GridLayoutProps, GridResponsiveColumnProps, ApprovedContentLayoutPattern, ApprovedShellRowConfig, HeaderShellNavigationItem, HeaderShellProps, HeaderShellUtilityAction, InlineNotificationKind, InlineNotificationProps, InlineNotificationStatus, IndexItem, IndexProps, LinkAppearance, LinkProps, LinkSize, LinkState, ModalFooterLayout, ModalProps, ModalTone, PaginationProps, ComponentGovernance, RadioProps, SearchInputProps, SelectInputOption, SelectInputProps, SelectInputSize, SelectInputTone, StructuredListCellAlignment, StructuredListColumn, StructuredListProps, StructuredListRow, TagColor, TagProps, TagSize, TabsItem, TabsOrientation, TabsProps, TooltipAlignment, TooltipPosition, TooltipProps, ToggleInputProps, ToggleInputSize, TokenShowcaseCardProps, TextInputProps, TextInputSize, TextInputTone, TextAreaProps, TextAreaSize, TextAreaTone, } from './types';
+export type { AccordionItem, AccordionProps, BreadcrumbItem, BreadcrumbProps, ButtonProps, ButtonSize, ButtonVariant, CardDetailItem, CardProps, CheckboxGroupProps, CheckboxProps, ContainedListItem, ContainedListProps, ContainedListVariant, DataTableCellAlignment, DataTableColumn, DataTableProps, DataTableRow, DescriptionListItem, DescriptionListProps, FormItemProps, FormProps, FormRowProps, GridBreakpoint, GridColumnProps, GridColumnSpan, GridColumnValue, GridLayoutProps, GridResponsiveColumnProps, ApprovedContentLayoutPattern, ApprovedLegacyContentLayoutPatternName, ApprovedShellRowConfig, CanonicalLayoutPattern, CanonicalLayoutPatternName, GridGeometryMode, HeaderShellNavigationItem, HeaderShellProps, HeaderShellUtilityAction, InlineNotificationKind, InlineNotificationProps, InlineNotificationStatus, IndexItem, IndexProps, LinkAppearance, LinkProps, LinkSize, LinkState, ModalFooterLayout, ModalProps, ModalTone, LayoutAdaptiveBehavior, LayoutScrollOwner, LayoutPatternBreakpoint, CanonicalLayoutPatternRegion, PaginationProps, ComponentGovernance, RadioProps, SearchInputProps, SelectInputOption, SelectInputProps, SelectInputSize, SelectInputTone, StructuredListCellAlignment, StructuredListColumn, StructuredListProps, StructuredListRow, TagColor, TagProps, TagSize, TabsItem, TabsOrientation, TabsProps, TooltipAlignment, TooltipPosition, TooltipProps, ToggleInputProps, ToggleInputSize, TokenShowcaseCardProps, TextInputProps, TextInputSize, TextInputTone, TextAreaProps, TextAreaSize, TextAreaTone, } from './types';
 export type { IconName, IconProps } from './components/Icon/Icon';
 //# sourceMappingURL=index.d.ts.map