@kcascend/liquid-ui 0.0.4 → 0.0.6

package/README.md

@@ -1,61 +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`.
-
-```tsx
-import { GridColumn, GridLayout } from '@kcascend/liquid-ui';
-
-export function Example() {
-  return (
-    <GridLayout as="div">
-      <GridColumn sm={4} md={4} lg={8}>
-        Primary
-      </GridColumn>
-      <GridColumn sm={2} md={2} lg={4}>
-        Secondary A
-      </GridColumn>
-      <GridColumn sm={2} md={2} lg={4}>
-        Secondary B
-      </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.
-
-## 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/Checkbox/Checkbox.d.ts

@@ -1,3 +1,4 @@
-import type { CheckboxProps } from '../../types';
+import type { CheckboxGroupProps, CheckboxProps } from '../../types';
 export declare function Checkbox({ className, id, indeterminate, label, hideLabel, style, disabled, ...props }: CheckboxProps): import("react/jsx-runtime").JSX.Element;
+export declare function CheckboxGroup({ legend, helperText, errorText, warningText, className, style, children, }: CheckboxGroupProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=Checkbox.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Checkbox.d.ts","sourceRoot":"","sources":["../../../src/components/Checkbox/Checkbox.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMjD,wBAAgB,QAAQ,CAAC,EACvB,SAAS,EACT,EAAE,EACF,aAAqB,EACrB,KAAK,EACL,SAAiB,EACjB,KAAK,EACL,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,aAAa,2CAkDf"}
+{"version":3,"file":"Checkbox.d.ts","sourceRoot":"","sources":["../../../src/components/Checkbox/Checkbox.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAMrE,wBAAgB,QAAQ,CAAC,EACvB,SAAS,EACT,EAAE,EACF,aAAqB,EACrB,KAAK,EACL,SAAiB,EACjB,KAAK,EACL,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,aAAa,2CAkDf;AAED,wBAAgB,aAAa,CAAC,EAC5B,MAAM,EACN,UAAU,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,KAAK,EACL,QAAQ,GACT,EAAE,kBAAkB,2CA0BpB"}

package/dist/components/Checkbox/Checkbox.js

@@ -15,3 +15,12 @@ export function Checkbox({ className, id, indeterminate = false, label, hideLabe
     }, [indeterminate]);
     return (_jsxs("label", { className: getClassName(className), style: style, "data-disabled": disabled || undefined, children: [_jsx("input", { ...props, ref: inputRef, type: "checkbox", id: inputId, disabled: disabled, className: "liquid-checkbox__input" }), _jsxs("span", { className: "liquid-checkbox__box", "aria-hidden": "true", children: [_jsx(Icon, { className: "liquid-checkbox__check-icon", color: "var(--component-checkbox-icon-check, #ffffff)", name: "check", size: 14 }), _jsx(Icon, { className: "liquid-checkbox__dash-icon", color: "var(--component-checkbox-icon-check, #ffffff)", name: "dash", size: 14 })] }), label ? (_jsx("span", { className: hideLabel ? 'liquid-sr-only' : 'liquid-checkbox__label-text', children: label })) : null] }));
 }
+export function CheckboxGroup({ legend, helperText, errorText, warningText, className, style, children, }) {
+    const statusText = errorText ?? warningText ?? helperText;
+    const statusClass = errorText
+        ? 'liquid-checkbox-group__status--error'
+        : warningText
+            ? 'liquid-checkbox-group__status--warning'
+            : 'liquid-checkbox-group__status--helper';
+    return (_jsxs("fieldset", { className: ['liquid-checkbox-group', className].filter(Boolean).join(' '), style: style, children: [legend ? (_jsx("legend", { className: "liquid-checkbox-group__legend", children: legend })) : null, _jsxs("div", { className: "liquid-checkbox-group__options-helper", children: [_jsx("div", { className: "liquid-checkbox-group__items", children: children }), statusText ? (_jsx("span", { className: `liquid-checkbox-group__status ${statusClass}`, children: statusText })) : null] })] }));
+}

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

@@ -0,0 +1,8 @@
+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<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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,317 @@
+function pickResponsiveColumns(columns) {
+    return columns;
+}
+function pickLayoutProps(props) {
+    return props;
+}
+function toGridColumnProps(columns) {
+    return columns;
+}
+export const approvedShellRows = {
+    header: {
+        description: 'Full-width header row aligned to the global shell column map.',
+        layout: pickLayoutProps({ fullWidth: true, withRowGap: false }),
+    },
+    search: {
+        description: 'Standard-gutter search row for filters and query controls.',
+        layout: pickLayoutProps({ fullWidth: false, withRowGap: false }),
+    },
+    results: {
+        description: 'Standard-gutter results row. Start from an approved content pattern before introducing bespoke spans.',
+        layout: pickLayoutProps({ fullWidth: false, withRowGap: false }),
+    },
+    footer: {
+        description: 'Full-width footer row for meta content and secondary actions.',
+        layout: pickLayoutProps({ fullWidth: true, withRowGap: false }),
+    },
+};
+export const approvedContentLayoutPatterns = {
+    single: {
+        description: 'Single-column content for forms, detail views, and uninterrupted reading flows.',
+        guidance: 'Prefer this when secondary content is optional or can move below the primary flow.',
+        regions: {
+            primary: pickResponsiveColumns({
+                sm: 4,
+                md: 8,
+                lg: 16,
+                xlg: 16,
+                max: 16,
+            }),
+        },
+    },
+    sidebarStart: {
+        description: 'Leading sidebar with primary content to the right.',
+        guidance: 'Use for filter, navigation, or status sidebars that should stack above content on smaller viewports.',
+        regions: {
+            primary: pickResponsiveColumns({
+                sm: 4,
+                md: 8,
+                lg: 12,
+                xlg: 12,
+                max: 12,
+            }),
+            secondary: pickResponsiveColumns({ sm: 4, md: 8, lg: 4, xlg: 4, max: 4 }),
+        },
+    },
+    sidebarEnd: {
+        description: 'Primary content first, with a trailing sidebar on wider breakpoints.',
+        guidance: 'Use for supporting context that should remain visible on desktop without preceding the main task.',
+        regions: {
+            primary: pickResponsiveColumns({
+                sm: 4,
+                md: 8,
+                lg: 12,
+                xlg: 12,
+                max: 12,
+            }),
+            secondary: pickResponsiveColumns({ sm: 4, md: 8, lg: 4, xlg: 4, max: 4 }),
+        },
+    },
+    splitEqual: {
+        description: 'Balanced two-up layout for peer content such as comparisons or dual work areas.',
+        guidance: 'Use when both regions have equal task weight. Avoid for filters or auxiliary status panels.',
+        regions: {
+            primary: pickResponsiveColumns({ sm: 4, md: 8, lg: 8, xlg: 8, max: 8 }),
+            secondary: pickResponsiveColumns({ sm: 4, md: 8, lg: 8, xlg: 8, max: 8 }),
+        },
+    },
+};
+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 {
+        primary: toGridColumnProps(pattern.regions.primary),
+        secondary: pattern.regions.secondary
+            ? toGridColumnProps(pattern.regions.secondary)
+            : undefined,
+        tertiary: pattern.regions.tertiary
+            ? toGridColumnProps(pattern.regions.tertiary)
+            : undefined,
+    };
+}

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"}