feat: add standalone content display preference component

build-tools/utils/pluralize.js

@@ -23,6 +23,7 @@ const pluralizationMap = {
   CollectionPreferences: 'CollectionPreferences',
   ColumnLayout: 'ColumnLayouts',
   Container: 'Containers',
+  ContentDisplayPreference: 'ContentDisplayPreferences',
   ContentLayout: 'ContentLayouts',
   CopyToClipboard: 'CopyToClipboards',
   DateInput: 'DateInputs',

pages/content-display-preference/simple.page.tsx

@@ -0,0 +1,93 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useState } from 'react';
+
+import Box from '~components/box';
+import ContentDisplayPreference, { ContentDisplayPreferenceProps } from '~components/content-display-preference';
+import SpaceBetween from '~components/space-between';
+import StatusIndicator from '~components/status-indicator';
+
+import ScreenshotArea from '../utils/screenshot-area';
+
+const options: ContentDisplayPreferenceProps['options'] = [
+  { id: 'id1', label: 'Distribution ID', alwaysVisible: true },
+  { id: 'id2', label: 'Domain name' },
+  { id: 'id3', label: 'Price class' },
+  { id: 'id4', label: 'Origin' },
+  { id: 'id5', label: 'Status' },
+  { id: 'id6', label: 'State' },
+];
+
+const MAX_VISIBLE = 3;
+
+const i18nStrings: ContentDisplayPreferenceProps.I18nStrings = {
+  columnFilteringPlaceholder: 'Filter columns',
+  columnFilteringAriaLabel: 'Filter columns',
+  columnFilteringClearFilterText: 'Clear filter',
+  columnFilteringNoMatchText: 'No columns match',
+  columnFilteringCountText: count => `${count} ${count === 1 ? 'match' : 'matches'}`,
+};
+
+export default function ContentDisplayPreferencePage() {
+  const [value, setValue] = useState<ContentDisplayPreferenceProps['value']>([
+    { id: 'id1', visible: true },
+    { id: 'id2', visible: true },
+    { id: 'id3', visible: true },
+    { id: 'id4', visible: false },
+    { id: 'id5', visible: false },
+    { id: 'id6', visible: false },
+  ]);
+
+  const visibleCount = (value ?? []).filter(item => item.visible).length;
+  const limitReached = visibleCount >= MAX_VISIBLE;
+
+  return (
+    <ScreenshotArea>
+      <Box padding="l">
+        <h1>Standalone ContentDisplayPreference</h1>
+        <SpaceBetween size="m">
+          <Box>
+            Reacts to changes immediately (no confirm step). This example rejects turning on more than {MAX_VISIBLE}{' '}
+            columns.
+          </Box>
+          {limitReached ? (
+            <StatusIndicator type="warning">
+              Maximum of {MAX_VISIBLE} visible columns reached. Hide a column to enable another.
+            </StatusIndicator>
+          ) : (
+            <StatusIndicator type="info">
+              {visibleCount} of {MAX_VISIBLE} visible columns selected.
+            </StatusIndicator>
+          )}
+          <div style={{ maxInlineSize: 400, border: '1px solid #d5dbdb', padding: 16, borderRadius: 8 }}>
+            <ContentDisplayPreference
+              title="Content display"
+              description="Select and reorder the columns to display."
+              options={options}
+              value={value}
+              enableColumnFiltering={true}
+              i18nStrings={i18nStrings}
+              dragHandleAriaLabel="Drag handle"
+              liveAnnouncementDndStarted={(position, total) => `Picked up item at position ${position} of ${total}`}
+              liveAnnouncementDndItemReordered={(initial, current, total) =>
+                `Moving item to position ${current} of ${total} (was ${initial})`
+              }
+              liveAnnouncementDndItemCommitted={(initial, final, total) =>
+                `Item moved from position ${initial} to position ${final} of ${total}`
+              }
+              liveAnnouncementDndDiscarded="Reordering canceled"
+              onChange={event => {
+                const nextVisible = event.detail.value.filter(item => item.visible).length;
+                // Only accept the change if it does not exceed the maximum number of visible columns.
+                if (nextVisible <= MAX_VISIBLE) {
+                  setValue(event.detail.value);
+                }
+              }}
+            />
+          </div>
+          <Box variant="code">{JSON.stringify(value)}</Box>
+        </SpaceBetween>
+      </Box>
+    </ScreenshotArea>
+  );
+}

src/__tests__/required-props-for-components.ts

@@ -10,6 +10,7 @@ const defaultProps: Record<string, Record<string, any>> = {
   autosuggest: { options: [], enteredPrefix: '' },
   'anchor-navigation': { anchors: [] },
   'code-editor': { i18nStrings },
+  'content-display-preference': { options: [] },
   wizard: {
     steps: [],
     i18nStrings: {

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

@@ -10551,6 +10551,270 @@ Refer to the [style](/components/container/?tabId=style) tab for more details.",
 }
 `;
 
+exports[`Components definition for content-display-preference matches the snapshot: content-display-preference 1`] = `
+{
+  "dashCaseName": "content-display-preference",
+  "events": [
+    {
+      "cancelable": false,
+      "description": "Called whenever the user reorders items or toggles their visibility.
+
+Unlike \`CollectionPreferences\`, the standalone component emits changes immediately, allowing you to
+react to selection before the user confirms (for example, to enforce a maximum number of visible columns).
+
+The event \`detail\` contains the following:
+- \`value\` (ReadonlyArray<ContentDisplayItem>) - The updated ordered list of items and their visibility.",
+      "detailInlineType": {
+        "name": "ContentDisplayPreferenceProps.ChangeDetail",
+        "properties": [
+          {
+            "name": "value",
+            "optional": false,
+            "type": "ReadonlyArray<CollectionPreferencesProps.ContentDisplayItem>",
+          },
+        ],
+        "type": "object",
+      },
+      "detailType": "ContentDisplayPreferenceProps.ChangeDetail",
+      "name": "onChange",
+    },
+  ],
+  "functions": [],
+  "name": "ContentDisplayPreference",
+  "properties": [
+    {
+      "deprecatedTag": "Custom CSS is not supported. For testing and other use cases, use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).",
+      "description": "Adds the specified classes to the root element of the component.",
+      "name": "className",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "description": "Specifies the description displayed below the title.",
+      "i18nTag": true,
+      "name": "description",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "name": "dragHandleAriaDescription",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "name": "dragHandleAriaLabel",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "description": "Adds a columns filter to the control.",
+      "name": "enableColumnFiltering",
+      "optional": true,
+      "type": "boolean",
+    },
+    {
+      "description": "Specifies an array of column group definitions for multi-level content display. Each group contains:
+- \`id\` (string) - A unique identifier for the group.
+- \`label\` (string) - The text displayed as the group label.",
+      "name": "groups",
+      "optional": true,
+      "type": "ReadonlyArray<CollectionPreferencesProps.ContentDisplayOptionGroup>",
+    },
+    {
+      "description": "An object containing all the localized strings required by the component.",
+      "i18nTag": true,
+      "inlineType": {
+        "name": "CollectionPreferencesProps.ContentDisplayPreferenceI18nStrings",
+        "properties": [
+          {
+            "name": "columnFilteringAriaLabel",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "name": "columnFilteringClearFilterText",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "inlineType": {
+              "name": "(count: number) => string",
+              "parameters": [
+                {
+                  "name": "count",
+                  "type": "number",
+                },
+              ],
+              "returnType": "string",
+              "type": "function",
+            },
+            "name": "columnFilteringCountText",
+            "optional": true,
+            "type": "((count: number) => string)",
+          },
+          {
+            "name": "columnFilteringNoMatchText",
+            "optional": true,
+            "type": "string",
+          },
+          {
+            "name": "columnFilteringPlaceholder",
+            "optional": true,
+            "type": "string",
+          },
+        ],
+        "type": "object",
+      },
+      "name": "i18nStrings",
+      "optional": true,
+      "type": "CollectionPreferencesProps.ContentDisplayPreferenceI18nStrings",
+    },
+    {
+      "deprecatedTag": "The usage of the \`id\` attribute is reserved for internal use cases. For testing and other use cases,
+use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes). If you must
+use the \`id\` attribute, consider setting it on a parent element instead.",
+      "description": "Adds the specified ID to the root element of the component.",
+      "name": "id",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "name": "liveAnnouncementDndDiscarded",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "description": "Adds a label for a group item to be announced by screen readers during drag and drop operations.",
+      "inlineType": {
+        "name": "(label: string, count: number) => string",
+        "parameters": [
+          {
+            "name": "label",
+            "type": "string",
+          },
+          {
+            "name": "count",
+            "type": "number",
+          },
+        ],
+        "returnType": "string",
+        "type": "function",
+      },
+      "name": "liveAnnouncementDndGroupLabel",
+      "optional": true,
+      "type": "((label: string, count: number) => string)",
+    },
+    {
+      "inlineType": {
+        "name": "(initialPosition: number, finalPosition: number, total: number) => string",
+        "parameters": [
+          {
+            "name": "initialPosition",
+            "type": "number",
+          },
+          {
+            "name": "finalPosition",
+            "type": "number",
+          },
+          {
+            "name": "total",
+            "type": "number",
+          },
+        ],
+        "returnType": "string",
+        "type": "function",
+      },
+      "name": "liveAnnouncementDndItemCommitted",
+      "optional": true,
+      "type": "((initialPosition: number, finalPosition: number, total: number) => string)",
+    },
+    {
+      "inlineType": {
+        "name": "(initialPosition: number, currentPosition: number, total: number) => string",
+        "parameters": [
+          {
+            "name": "initialPosition",
+            "type": "number",
+          },
+          {
+            "name": "currentPosition",
+            "type": "number",
+          },
+          {
+            "name": "total",
+            "type": "number",
+          },
+        ],
+        "returnType": "string",
+        "type": "function",
+      },
+      "name": "liveAnnouncementDndItemReordered",
+      "optional": true,
+      "type": "((initialPosition: number, currentPosition: number, total: number) => string)",
+    },
+    {
+      "inlineType": {
+        "name": "(position: number, total: number) => string",
+        "parameters": [
+          {
+            "name": "position",
+            "type": "number",
+          },
+          {
+            "name": "total",
+            "type": "number",
+          },
+        ],
+        "returnType": "string",
+        "type": "function",
+      },
+      "name": "liveAnnouncementDndStarted",
+      "optional": true,
+      "type": "((position: number, total: number) => string)",
+    },
+    {
+      "description": "Specifies an array of options for reordering and visible content selection.
+
+Each option contains the following:
+- \`id\` (string) - Corresponds to a table column \`id\`.
+- \`label\` (string) - Specifies a short description of the content.
+- \`alwaysVisible\` (boolean) - (Optional) Determines whether the visibility is always on and therefore cannot be toggled. This is set to \`false\` by default.",
+      "name": "options",
+      "optional": false,
+      "type": "ReadonlyArray<CollectionPreferencesProps.ContentDisplayOption>",
+    },
+    {
+      "description": "Specifies the text displayed at the top of the preference.",
+      "i18nTag": true,
+      "name": "title",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "description": "The current, ordered list of content items and their visibility. The order of the elements influences the display.
+
+Each content display item is one of the following:
+- \`ContentDisplayColumn\` - Represents a single column.
+  - \`type\` ('column') - (Optional) Identifies the entry as a column. Defaults to \`'column'\` when omitted.
+  - \`id\` (string) - The column identifier.
+  - \`visible\` (boolean) - Whether the column is visible.
+- \`ContentDisplayGroup\` - Represents a column group.
+  - \`type\` ('group') - Identifies the entry as a group.
+  - \`id\` (string) - The group identifier.
+  - \`visible\` (boolean) - Whether the group is visible.
+  - \`children\` (ReadonlyArray<ContentDisplayItem>) - The columns or nested groups within this group.
+
+When not provided, all options are shown as visible in their original order.",
+      "name": "value",
+      "optional": true,
+      "type": "ReadonlyArray<CollectionPreferencesProps.ContentDisplayItem>",
+    },
+  ],
+  "regions": [],
+  "releaseStatus": "stable",
+}
+`;
+
 exports[`Components definition for content-layout matches the snapshot: content-layout 1`] = `
 {
   "dashCaseName": "content-layout",

src/__tests__/snapshot-tests/__snapshots__/test-utils-selectors.test.tsx.snap

@@ -200,6 +200,9 @@ exports[`test-utils selectors 1`] = `
     "awsui_media_14iqq",
     "awsui_root_14iqq",
   ],
+  "content-display-preference": [
+    "awsui_root_1bte3",
+  ],
   "content-layout": [
     "awsui_breadcrumbs_64tge",
     "awsui_content_5gtk3",