Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions packages/widget-dashboard/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,15 @@
registered type be inserted
([#81967](https://github.com/WordPress/gutenberg/pull/81967)).

### Enhancements

- `gridSettings.columns` now sets the wide-container column count (floored,
with a floor of one); the responsive steps scale from it.
`WIDGET_DASHBOARD_COLUMN_COUNT` is the default when the host sets
nothing, and the wp-admin dashboard pins it where it reads its stored
settings, so preferences persisted by the removed Columns control stay
inert ([#82204](https://github.com/WordPress/gutenberg/pull/82204)).

### Internal

- Remove unused dependency `@wordpress/primitives` ([#82103](https://github.com/WordPress/gutenberg/pull/82103)).
Expand Down
2 changes: 1 addition & 1 deletion packages/widget-dashboard/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -252,7 +252,7 @@ The exported kit for handling them:
- `DEFAULT_GRID` — canonical default settings, applied when `gridSettings` is omitted.
- `normalizeGridSettings( settings, defaultRowHeight )` — coerces legacy freeform row heights to the nearest preset. Run it over stored payloads before passing them in.
- `ROW_HEIGHT_PRESETS` / `DEFAULT_ROW_HEIGHT` — the row-height presets (`small`, `medium`, `large`) that `rowHeight` values normalize to.
- `WIDGET_DASHBOARD_COLUMN_COUNT` — maximum column count on wide containers. The effective count steps down from container width; persisted `columns` values are ignored.
- `WIDGET_DASHBOARD_COLUMN_COUNT` — column count used on wide containers when the host sets no `gridSettings.columns`. A default, not a ceiling: a finite `columns` is floored, with a floor of `1`, and rendered as asked. The effective count steps down from container width: the count at `960px` and above, `min( 2, count )` below that, one column below `600px`.

```tsx
<WidgetDashboard
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -131,8 +131,10 @@ export const Widgets = forwardRef< HTMLDivElement, WidgetsProps >(
widgetTypes,
canPerform,
} = useDashboardInternalContext();
const { containerRef, columnCount } =
useDashboardContainerColumnCount( ref );
const { containerRef, columnCount } = useDashboardContainerColumnCount(
ref,
gridSettings.columns
);
const isMasonry = gridSettings.model === 'masonry';

const permissionsFor = useCallback< TilePermissionsFor >(
Expand Down
4 changes: 2 additions & 2 deletions packages/widget-dashboard/src/context/dashboard-context.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,14 @@ import type {
} from '@wordpress/widget-primitives';
import { DEFAULT_GRID } from '../utils/default-grid';
import { normalizeGridSettings } from '../utils/normalize-grid-settings';
import { resolveDashboardColumnCap } from '../utils/resolve-dashboard-column-count/resolve-dashboard-column-count';
import { DEFAULT_ROW_HEIGHT } from '../utils/row-height-presets';
import { useDashboardPolicy } from '../components/dashboard-policy';
import type {
CanPerformDashboardOperation,
WidgetGridSettings,
DashboardWidget,
} from '../types';
import { WIDGET_DASHBOARD_COLUMN_COUNT } from '../types';

type GridSettingsWithColumns = WidgetGridSettings & { columns: number };

Expand All @@ -32,7 +32,7 @@ function resolveGridSettings(
const normalized = normalizeGridSettings( settings, DEFAULT_ROW_HEIGHT );
return {
...normalized,
columns: WIDGET_DASHBOARD_COLUMN_COUNT,
columns: resolveDashboardColumnCap( normalized.columns ),
};
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,15 @@ interface UseDashboardContainerColumnCountResult {

/**
* Tracks the dashboard grid container width and maps it to an opinionated
* column count (4 → 2 → 1). Measurement is container-based via
* column count (cap → 2 → 1). Measurement is container-based via
* `ResizeObserver`, not viewport media queries.
*
* @param {Ref< HTMLDivElement >} [forwardedRef] Ref forwarded from the grid wrapper.
* @param {number} [maxColumns] Column cap for wide containers.
*/
export function useDashboardContainerColumnCount(
forwardedRef?: Ref< HTMLDivElement >
forwardedRef?: Ref< HTMLDivElement >,
maxColumns?: number
): UseDashboardContainerColumnCountResult {
const [ container, setContainer ] = useState< HTMLDivElement | null >(
null
Expand Down Expand Up @@ -48,8 +50,8 @@ export function useDashboardContainerColumnCount(
}, [ container ] );

const columnCount = useMemo(
() => resolveDashboardColumnCount( containerWidth ),
[ containerWidth ]
() => resolveDashboardColumnCount( containerWidth, maxColumns ),
[ containerWidth, maxColumns ]
);

return { containerRef, columnCount };
Expand Down
123 changes: 123 additions & 0 deletions packages/widget-dashboard/src/stories/index.story.tsx
Comment thread
Nikschavan marked this conversation as resolved.
Resolved
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ import type {
WidgetRenderProps,
WidgetType,
} from '@wordpress/widget-primitives';
import { ROW_HEIGHT_PRESETS } from '../utils/row-height-presets';
import type { RowHeightPreset } from '../utils/row-height-presets';
import { WidgetDashboard } from '../widget-dashboard';
import type { CanPerformDashboardOperation, DashboardWidget } from '../types';

Expand Down Expand Up @@ -787,3 +789,124 @@ Nested policies compose restrictively; without a policy, every operation is allo
},
},
};

// A fuller board than INITIAL_LAYOUT: a hero spanning the whole first row at
// any column count (the grid clamps the span), then a rank of small tiles so
// the columns control visibly repacks them.
const GRID_SETTINGS_LAYOUT: DashboardWidget[] = [
{
uuid: 'grid-settings-traffic-week',
type: 'demo/traffic-snapshot',
attributes: { metric: 'views', period: 'week', label: 'Traffic' },
placement: { width: 2, height: 1, order: 1 },
},
{
uuid: 'grid-settings-goal-revenue',
type: 'demo/goal-progress',
attributes: { metric: 'revenue', target: '5000' },
placement: { width: 1, height: 1, order: 2 },
},
{
uuid: 'grid-settings-audience-tall',
type: 'demo/traffic-snapshot',
attributes: { metric: 'visitors', period: 'month', label: 'Audience' },
placement: { width: 1, height: 2, order: 3 },
},
{
uuid: 'grid-settings-goal-orders',
type: 'demo/goal-progress',
attributes: { metric: 'orders', target: '1000' },
placement: { width: 2, height: 1, order: 4 },
},
{
uuid: 'grid-settings-traffic-day',
type: 'demo/traffic-snapshot',
attributes: { metric: 'views', period: 'day', label: 'Today' },
placement: { width: 1, height: 1, order: 5 },
},
{
uuid: 'grid-settings-goal-stretch',
type: 'demo/goal-progress',
attributes: { metric: 'revenue', target: '10000' },
placement: { width: 1, height: 1, order: 6 },
},
];

type GridSettingsStoryProps = {
columns: number;
model: 'grid' | 'masonry';
rowHeight: RowHeightPreset;
};

function GridSettingsStory( {
columns,
model,
rowHeight,
}: GridSettingsStoryProps ) {
const [ layout, setLayout ] =
useState< DashboardWidget[] >( GRID_SETTINGS_LAYOUT );
const [ editMode, setEditMode ] = useState( false );

return (
<WidgetDashboard
widgetTypes={ [
trafficSnapshotWidgetType,
goalProgressWidgetType,
] }
layout={ layout }
onLayoutChange={ setLayout }
editMode={ editMode }
onEditChange={ setEditMode }
resolveWidgetModule={ resolveDemoModule }
gridSettings={ {
model,
columns,
rowHeight: ROW_HEIGHT_PRESETS[ rowHeight ],
} }
>
<Page
title="Dashboard"
subTitle={ `Standard grid, ${ columns } columns on a wide container, stepping down to 2 and then one as it narrows.` }
actions={ <WidgetDashboard.Actions /> }
showSidebarToggle={ false }
hasPadding
>
<WidgetDashboard.Widgets />
</Page>
</WidgetDashboard>
);
}

export const GridSettings: StoryObj< GridSettingsStoryProps > = {
render: ( args ) => <GridSettingsStory { ...args } />,
args: {
columns: 4,
model: 'grid',
rowHeight: 'medium',
},
argTypes: {
columns: {
control: { type: 'range', min: 1, max: 12, step: 1 },
description:
'Wide-container column count. The host decides; the package only floors it at one.',
},
model: {
control: 'radio',
options: [ 'grid', 'masonry' ],
},
rowHeight: {
control: 'radio',
options: Object.keys( ROW_HEIGHT_PRESETS ),
},
},
parameters: {
controls: { include: [ 'columns', 'model', 'rowHeight' ] },
docs: {
description: {
story: `
The \`gridSettings\` prop carries the host's layout decisions. \`columns\` sets the wide-container count — \`WIDGET_DASHBOARD_COLUMN_COUNT\` is only the default when the host sets nothing — and container width steps the effective count down to \`min( 2, count )\` and then one as it narrows. Drag the columns control; resize the canvas to watch the steps.
`,
},
},
},
};
22 changes: 13 additions & 9 deletions packages/widget-dashboard/src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -112,18 +112,19 @@ export interface WidgetContextValue {
export type WidgetGridModel = 'grid' | 'masonry';

/**
* Maximum column count for the widget dashboard on wide containers.
* Not user-configurable; container width steps the count down to two
* and one column at fixed breakpoints.
* Column count used on wide containers when the host sets no
* `gridSettings.columns`. A default, not a ceiling: the package renders
* whatever count the host asks for. The four-column wp-admin dashboard is
* that page's own decision, pinned where it reads its stored settings.
*/
export const WIDGET_DASHBOARD_COLUMN_COUNT = 4;

/**
* Settings common to every grid model. Column count is resolved from
* the dashboard container width (see
* `utils/resolve-dashboard-column-count`). `columns` and `minColumnWidth`
* on this type remain for persisted payloads and `@wordpress/grid`
* compatibility; the dashboard ignores user-facing values for both.
* the host's cap and the dashboard container width (see
* `utils/resolve-dashboard-column-count`). `minColumnWidth` remains for
* persisted payloads and `@wordpress/grid` compatibility; the dashboard
* ignores it.
*
* `spacing` is intentionally absent: the gap between tiles is
* presentational and lives with the design-system theme/density, not
Expand All @@ -132,8 +133,11 @@ export const WIDGET_DASHBOARD_COLUMN_COUNT = 4;
*/
interface BaseWidgetGridSettings {
/**
* Target column count (cap). The dashboard always uses
* {@link WIDGET_DASHBOARD_COLUMN_COUNT}; persisted values are ignored.
* Column count on wide containers. A finite value is floored, with a
* floor of one and no ceiling; an absent or non-finite value resolves to
* {@link WIDGET_DASHBOARD_COLUMN_COUNT}. Container width steps the
* effective count down: `min( 2, count )` in the middle band, one
* column below it.
*/
columns?: number;

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,32 +7,54 @@ import { WIDGET_DASHBOARD_COLUMN_COUNT } from '../../types';
export const WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_ONE_COLUMN = 600;

/**
* Container width (px) below which the dashboard drops from four columns
* to two. Above this threshold (and below the four-column cap) the
* grid uses {@link WIDGET_DASHBOARD_COLUMN_COUNT}.
* Container width (px) below which the dashboard drops from the column
* cap to two. Above this threshold the grid uses the cap itself.
*/
export const WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_TWO_COLUMNS = 960;

/**
* Resolves the wide-container column count a host asked for. A finite value
* is floored, with a floor of one and no ceiling: how many columns a surface
* can carry is the host's decision, not the package's. An absent or
* non-finite value resolves to {@link WIDGET_DASHBOARD_COLUMN_COUNT}.
*
* @param columns Host-provided `gridSettings.columns`, if any.
* @return Column count for wide containers.
*/
export function resolveDashboardColumnCap( columns?: number ): number {
if ( typeof columns !== 'number' || ! Number.isFinite( columns ) ) {
return WIDGET_DASHBOARD_COLUMN_COUNT;
}

return Math.max( 1, Math.floor( columns ) );
}

/**
* Resolves the dashboard grid column count from the widget surface
* container width. Uses discrete steps (4 → 2 → 1), not viewport
* container width. Uses discrete steps (cap → 2 → 1), not viewport
* media queries.
*
* @param containerWidth Measured inline size of the dashboard grid container.
* @param maxColumns Column cap for wide containers; see
* {@link resolveDashboardColumnCap}.
* @return Column count for {@link @wordpress/grid} surfaces.
*/
export function resolveDashboardColumnCount( containerWidth: number ): number {
export function resolveDashboardColumnCount(
containerWidth: number,
maxColumns: number = WIDGET_DASHBOARD_COLUMN_COUNT
): number {
if ( containerWidth <= 0 ) {
return WIDGET_DASHBOARD_COLUMN_COUNT;
return maxColumns;
}

if ( containerWidth < WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_ONE_COLUMN ) {
return 1;
}

if ( containerWidth < WIDGET_DASHBOARD_CONTAINER_BREAKPOINT_TWO_COLUMNS ) {
return 2;
// A cap of one must not step up to two in the middle band.
return Math.min( 2, maxColumns );
}

return WIDGET_DASHBOARD_COLUMN_COUNT;
return maxColumns;
}
Loading
Loading