@kcascend/liquid-ui 0.0.4 → 0.0.5

package/README.md

@@ -10,23 +10,22 @@
 
 ## Grid usage
 
-The package exposes a grid primitive through `GridLayout` and `GridColumn`.
+The package exposes a grid primitive through `GridLayout` and `GridColumn`, plus an approved layout catalog for application shells and content regions.
 
 ```tsx
-import { GridColumn, GridLayout } from '@kcascend/liquid-ui';
+import {
+  approvedContentLayoutPatterns,
+  GridColumn,
+  GridLayout,
+} from '@kcascend/liquid-ui';
 
 export function Example() {
+  const layout = approvedContentLayoutPatterns.sidebarEnd;
+
   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>
+      <GridColumn {...layout.regions.primary}>Primary</GridColumn>
+      <GridColumn {...layout.regions.secondary}>Secondary</GridColumn>
     </GridLayout>
   );
 }
@@ -42,6 +41,12 @@ Supported layout features:
 - `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

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/GridLayout/layoutPatterns.d.ts

@@ -0,0 +1,5 @@
+import type { 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 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,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"}

package/dist/components/GridLayout/layoutPatterns.js

@@ -0,0 +1,90 @@
+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 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,
+    };
+}