@cratis/scene.blueprint.default 4.31.0 → 4.33.0

package/foundation/ActionButton.tsx

@@ -0,0 +1,39 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ReactNode } from 'react';
+import { PermissionRule } from './PermissionRule';
+
+export interface ActionButtonProps {
+    /** The permission rule that decides whether the control works, refuses or is not rendered. */
+    rule?: PermissionRule;
+
+    /** Why the control is disabled, announced and shown as its tooltip. */
+    disabledReason: string;
+
+    /** What the control does when pressed. */
+    onClick?: (event: { stopPropagation(): void }) => void;
+
+    /** The emphasis of the button. */
+    emphasis?: 'primary' | 'secondary' | 'quiet';
+
+    children: ReactNode;
+}
+
+/**
+ * The one button every foundation component starts an action with, so the permission rule of spec Part B 1.5 is honoured in one place:
+ * hidden renders nothing; disabled stays focusable-by-description (`aria-disabled`) and carries the reason, rather than a bare
+ * greyed control nobody can explain.
+ */
+export function ActionButton({ rule = PermissionRule.Enabled, disabledReason, onClick, emphasis = 'primary', children }: ActionButtonProps) {
+    if (rule === PermissionRule.Hidden) return undefined;
+
+    const disabled = rule === PermissionRule.Disabled;
+    return (
+        <button type='button' className='foundation-button' data-emphasis={emphasis} aria-disabled={disabled || undefined}
+            title={disabled ? disabledReason : undefined} onClick={disabled ? undefined : onClick}>
+            {children}
+            {disabled && <span className='foundation-visually-hidden'>{`. ${disabledReason}`}</span>}
+        </button>
+    );
+}

package/foundation/ChartWrapper.tsx

@@ -0,0 +1,252 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useId, useRef } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readOptionalString, readStrings } from '../shell/elementProperties';
+import { ChartKind, ChartSeries, dataMaximum, donutSlices, funnelStages, niceScale, readSeries, ringPath } from './chartGeometry';
+import { ComponentState, readComponentState } from './ComponentState';
+import { formatNumber, NumberFormat, readLocale, readNumberFormat } from './formatting';
+import { readFoundationStrings } from './foundationStrings';
+import { FoundationFrame } from './StateFrame';
+import { useElementWidth } from './useElementWidth';
+
+/** Reads the chart kind, defaulting to a line chart. */
+export function readChartKind(value: unknown): ChartKind {
+    return (Object.values(ChartKind) as string[]).includes(value as string) ? (value as ChartKind) : ChartKind.Line;
+}
+
+/** The theme tokens series are drawn in, in order; a series is never told apart by color alone - see `markers` and `patterns`. */
+const seriesColors = ['var(--foundation-primary)', 'var(--foundation-success)', 'var(--foundation-warning)', 'var(--foundation-danger)', 'var(--foundation-info)', 'var(--foundation-muted)'];
+const markers = ['circle', 'square', 'triangle', 'diamond', 'cross', 'ring'] as const;
+const dashes = ['', '6 3', '2 3', '8 3 2 3', '', '4 4'];
+const margin = { top: 12, right: 12, bottom: 28, left: 48 };
+
+type Marker = (typeof markers)[number];
+
+function MarkerShape({ kind, x, y, color }: { kind: Marker; x: number; y: number; color: string }) {
+    const r = 4;
+    switch (kind) {
+        case 'square': return <rect x={x - r} y={y - r} width={r * 2} height={r * 2} fill={color} />;
+        case 'triangle': return <polygon points={`${x},${y - r - 1} ${x + r + 1},${y + r} ${x - r - 1},${y + r}`} fill={color} />;
+        case 'diamond': return <polygon points={`${x},${y - r - 1} ${x + r + 1},${y} ${x},${y + r + 1} ${x - r - 1},${y}`} fill={color} />;
+        case 'cross': return <path d={`M ${x - r} ${y - r} L ${x + r} ${y + r} M ${x + r} ${y - r} L ${x - r} ${y + r}`} stroke={color} strokeWidth={2} fill='none' />;
+        case 'ring': return <circle cx={x} cy={y} r={r} fill='none' stroke={color} strokeWidth={2} />;
+        default: return <circle cx={x} cy={y} r={r} fill={color} />;
+    }
+}
+
+interface PlotProps {
+    kind: ChartKind;
+    categories: string[];
+    series: ChartSeries[];
+    width: number;
+    locale: string;
+    format: NumberFormat;
+    currency?: string;
+}
+
+function CartesianPlot({ kind, categories, series, width, locale, format, currency }: PlotProps) {
+    const height = Math.max(180, Math.min(320, Math.round(width * 0.55)));
+    const plotWidth = width - margin.left - margin.right;
+    const plotHeight = height - margin.top - margin.bottom;
+    const scale = niceScale(dataMaximum(kind, series, categories.length));
+    const y = (value: number) => margin.top + plotHeight - (value / scale.maximum) * plotHeight;
+    const slot = plotWidth / Math.max(1, categories.length);
+    const patternId = useId();
+    const label = (value: number) => formatNumber(value, locale, format === NumberFormat.Number ? NumberFormat.Compact : format, currency);
+
+    return (
+        <svg className='foundation-chart-plot' viewBox={`0 0 ${width} ${height}`} width={width} height={height} aria-hidden='true' focusable='false'>
+            <defs>
+                {series.map((_, index) => index > 0 && index % 3 !== 0 && (
+                    <pattern key={index} id={`${patternId}-${index}`} width='6' height='6' patternUnits='userSpaceOnUse' patternTransform={`rotate(${index % 2 === 0 ? 45 : -45})`}>
+                        <rect width='6' height='6' fill={seriesColors[index % seriesColors.length]} opacity='0.35' />
+                        <line x1='0' y1='0' x2='0' y2='6' stroke={seriesColors[index % seriesColors.length]} strokeWidth='2.5' />
+                    </pattern>
+                ))}
+            </defs>
+            {scale.ticks.map(tick => (
+                <g key={tick}>
+                    <line className='foundation-chart-grid' x1={margin.left} x2={width - margin.right} y1={y(tick)} y2={y(tick)} />
+                    <text className='foundation-chart-tick' x={margin.left - 6} y={y(tick)} textAnchor='end' dominantBaseline='middle'>{label(tick)}</text>
+                </g>
+            ))}
+            {categories.map((category, index) => (
+                <text key={category + index} className='foundation-chart-tick' x={margin.left + slot * index + slot / 2} y={height - 8} textAnchor='middle'>{category}</text>
+            ))}
+            {kind === ChartKind.Line && series.map((item, seriesIndex) => {
+                const color = seriesColors[seriesIndex % seriesColors.length];
+                const points = categories.map((_, index) => ({ x: margin.left + slot * index + slot / 2, y: y(item.values[index] ?? 0) }));
+                return (
+                    <g key={item.name}>
+                        <polyline points={points.map(point => `${point.x},${point.y}`).join(' ')} fill='none' stroke={color} strokeWidth='2.5' strokeDasharray={dashes[seriesIndex % dashes.length]} />
+                        {points.map((point, index) => <MarkerShape key={index} kind={markers[seriesIndex % markers.length]} x={point.x} y={point.y} color={color} />)}
+                    </g>
+                );
+            })}
+            {kind === ChartKind.Bar && series.map((item, seriesIndex) => {
+                const group = slot * 0.7;
+                const bar = group / series.length;
+                return (
+                    <g key={item.name}>
+                        {categories.map((_, index) => {
+                            const value = Math.max(0, item.values[index] ?? 0);
+                            return <rect key={index} className='foundation-chart-bar' x={margin.left + slot * index + (slot - group) / 2 + bar * seriesIndex} y={y(value)} width={Math.max(1, bar - 2)} height={margin.top + plotHeight - y(value)}
+                                fill={fillFor(seriesIndex, patternId)} stroke={seriesColors[seriesIndex % seriesColors.length]} strokeWidth='1.5' />;
+                        })}
+                    </g>
+                );
+            })}
+            {kind === ChartKind.Stacked && categories.map((_, index) => {
+                let base = 0;
+                return (
+                    <g key={index}>
+                        {series.map((item, seriesIndex) => {
+                            const value = Math.max(0, item.values[index] ?? 0);
+                            const top = y(base + value);
+                            const rect = <rect key={item.name} className='foundation-chart-bar' x={margin.left + slot * index + slot * 0.15} y={top} width={slot * 0.7} height={Math.max(0, y(base) - top)}
+                                fill={fillFor(seriesIndex, patternId)} stroke={seriesColors[seriesIndex % seriesColors.length]} strokeWidth='1.5' />;
+                            base += value;
+                            return rect;
+                        })}
+                    </g>
+                );
+            })}
+        </svg>
+    );
+}
+
+function fillFor(seriesIndex: number, patternId: string): string {
+    return seriesIndex === 0 || seriesIndex % 3 === 0 ? seriesColors[seriesIndex % seriesColors.length] : `url(#${patternId}-${seriesIndex})`;
+}
+
+function DonutPlot({ categories, values, width, locale }: { categories: string[]; values: number[]; width: number; locale: string }) {
+    const size = Math.max(160, Math.min(280, width));
+    const radius = size / 2 - 4;
+    const slices = donutSlices(values);
+    const patternId = useId();
+
+    return (
+        <svg className='foundation-chart-plot' viewBox={`0 0 ${size} ${size}`} width={size} height={size} aria-hidden='true' focusable='false'>
+            <defs>
+                {values.map((_, index) => index > 0 && index % 3 !== 0 && (
+                    <pattern key={index} id={`${patternId}-${index}`} width='6' height='6' patternUnits='userSpaceOnUse' patternTransform={`rotate(${index % 2 === 0 ? 45 : -45})`}>
+                        <rect width='6' height='6' fill={seriesColors[index % seriesColors.length]} opacity='0.35' />
+                        <line x1='0' y1='0' x2='0' y2='6' stroke={seriesColors[index % seriesColors.length]} strokeWidth='2.5' />
+                    </pattern>
+                ))}
+            </defs>
+            {slices.map(slice => (
+                <path key={slice.index} className='foundation-chart-slice' d={ringPath(size / 2, size / 2, radius, radius * 0.6, slice.start, slice.end)} fill={fillFor(slice.index, patternId)}
+                    stroke={seriesColors[slice.index % seriesColors.length]} strokeWidth='1.5' data-share={formatNumber(slice.share * 100, locale, NumberFormat.Percent)}>
+                    <title>{`${categories[slice.index] ?? ''}: ${formatNumber(slice.share * 100, locale, NumberFormat.Percent)}`}</title>
+                </path>
+            ))}
+        </svg>
+    );
+}
+
+function FunnelPlot({ categories, values, width, locale, format, currency }: { categories: string[]; values: number[]; width: number; locale: string; format: NumberFormat; currency?: string }) {
+    const stages = funnelStages(values);
+    const barHeight = 34;
+    const gap = 6;
+    const height = stages.length * (barHeight + gap);
+    const patternId = useId();
+
+    return (
+        <svg className='foundation-chart-plot' viewBox={`0 0 ${width} ${height}`} width={width} height={height} aria-hidden='true' focusable='false'>
+            <defs>
+                {stages.map(stage => stage.index > 0 && stage.index % 3 !== 0 && (
+                    <pattern key={stage.index} id={`${patternId}-${stage.index}`} width='6' height='6' patternUnits='userSpaceOnUse' patternTransform='rotate(45)'>
+                        <rect width='6' height='6' fill={seriesColors[stage.index % seriesColors.length]} opacity='0.35' />
+                        <line x1='0' y1='0' x2='0' y2='6' stroke={seriesColors[stage.index % seriesColors.length]} strokeWidth='2.5' />
+                    </pattern>
+                ))}
+            </defs>
+            {stages.map(stage => {
+                const stageWidth = Math.max(2, width * stage.widthRatio);
+                return (
+                    <g key={stage.index}>
+                        <rect className='foundation-chart-bar' x={(width - stageWidth) / 2} y={stage.index * (barHeight + gap)} width={stageWidth} height={barHeight} rx='4'
+                            fill={fillFor(stage.index, patternId)} stroke={seriesColors[stage.index % seriesColors.length]} strokeWidth='1.5' />
+                        <text className='foundation-chart-stage' x={width / 2} y={stage.index * (barHeight + gap) + barHeight / 2} textAnchor='middle' dominantBaseline='middle'>
+                            {`${categories[stage.index] ?? ''} · ${formatNumber(stage.value, locale, format, currency)}`}
+                        </text>
+                    </g>
+                );
+            })}
+        </svg>
+    );
+}
+
+/**
+ * The `chartWrapper` component: one chart - line, bar, stacked, donut or funnel - drawn as scalable vector graphics from the
+ * theme's tokens, with its own title, legend and a data table.
+ *
+ * `categories` name the points and `series` give a list of values for each. A donut and a funnel draw the first series, one slice or
+ * stage per category. The chart is never the only way to read the data: the figure is labelled, the drawing is hidden from assistive
+ * technology, and a table of the same numbers follows it - open it with "Chart data". Series are told apart by marker, dash or hatch as
+ * well as color, and the legend names each.
+ */
+export function ChartWrapper({ element, interactions }: RegisteredComponentProps) {
+    const kind = readChartKind(element.properties.kind);
+    const categories = readStrings(element, 'categories');
+    const series = readSeries(element.properties.series);
+    const hasData = series.some(item => item.values.length > 0) && categories.length > 0;
+    const state = readComponentState(element, hasData);
+    const locale = readLocale(element);
+    const format = readNumberFormat(element);
+    const currency = readOptionalString(element, 'currency');
+    const strings = readFoundationStrings(element);
+    const container = useRef<HTMLDivElement>(null);
+    const width = useElementWidth(container, 480);
+    const title = readOptionalString(element, 'title') ?? readOptionalString(element, 'label');
+    const first = series[0]?.values ?? [];
+    const single = kind === ChartKind.Donut || kind === ChartKind.Funnel;
+    const legend = single ? categories.map((name, index) => ({ name, index })) : series.map((item, index) => ({ name: item.name, index }));
+    const dataTableId = useId();
+
+    return (
+        <FoundationFrame element={{ ...element, properties: { ...element.properties, label: title } }} interactions={interactions} name='chart' state={state} skeleton={[30, 100, 100, 60]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && (
+                <figure className='foundation-chart-figure' data-kind={kind}>
+                    {title && <figcaption className='foundation-chart-title'>{title}</figcaption>}
+                    <div ref={container} className='foundation-chart-canvas'>
+                        {kind === ChartKind.Donut ? <DonutPlot categories={categories} values={first} width={width} locale={locale} />
+                            : kind === ChartKind.Funnel ? <FunnelPlot categories={categories} values={first} width={width} locale={locale} format={format} currency={currency} />
+                                : <CartesianPlot kind={kind} categories={categories} series={series} width={width} locale={locale} format={format} currency={currency} />}
+                    </div>
+                    <ul className='foundation-chart-legend' aria-label={strings.chartSeries}>
+                        {legend.map(entry => (
+                            <li key={entry.index}>
+                                <svg width='14' height='14' viewBox='0 0 14 14' aria-hidden='true'>
+                                    {kind === ChartKind.Line ? <MarkerShape kind={markers[entry.index % markers.length]} x={7} y={7} color={seriesColors[entry.index % seriesColors.length]} />
+                                        : <rect x='1' y='1' width='12' height='12' fill={seriesColors[entry.index % seriesColors.length]} opacity={entry.index === 0 || entry.index % 3 === 0 ? 1 : 0.5} stroke={seriesColors[entry.index % seriesColors.length]} strokeWidth='2' />}
+                                </svg>
+                                <span>{entry.name}</span>
+                            </li>
+                        ))}
+                    </ul>
+                    <details className='foundation-chart-data'>
+                        <summary>{strings.chartDataTable}</summary>
+                        <table id={dataTableId}>
+                            <caption className='foundation-visually-hidden'>{title ?? strings.chartDataTable}</caption>
+                            <thead>
+                                <tr><th scope='col'>{strings.chartCategory}</th>{(single ? [{ name: series[0]?.name ?? strings.chartSeries }] : series).map(item => <th key={item.name} scope='col'>{item.name}</th>)}</tr>
+                            </thead>
+                            <tbody>
+                                {categories.map((category, index) => (
+                                    <tr key={category + index}>
+                                        <th scope='row'>{category}</th>
+                                        {(single ? [series[0]] : series).map(item => <td key={item?.name}>{formatNumber(item?.values[index] ?? 0, locale, format, currency)}</td>)}
+                                    </tr>
+                                ))}
+                            </tbody>
+                        </table>
+                    </details>
+                </figure>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/ColumnChooser.tsx

@@ -0,0 +1,73 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { KeyboardEvent, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { ChooserColumn, moveColumn, readColumns, toggleColumn, visibleColumnIds } from './columnModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon } from './FoundationIcon';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { FoundationFrame } from './StateFrame';
+
+/**
+ * The `columnChooser` component: which columns a table shows, and in what order.
+ *
+ * `columns` lists what could be shown (id, label, whether it starts visible, and whether it is locked - the identifying column is). The
+ * chooser is a button that discloses a list of checkboxes; each row also has move up and move down buttons, so ordering needs no
+ * drag-and-drop. Its `value` output is the ordered list of visible ids, which the table binds its columns to. Escape closes the list and
+ * returns focus to the button.
+ */
+export function ColumnChooser({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const supplied = useMemo(() => readColumns(element.properties.columns), [element.properties.columns]);
+    const suppliedKey = JSON.stringify(supplied);
+    const [columns, setColumns] = useState<ChooserColumn[]>(supplied);
+    const [open, setOpen] = useState(false);
+    const strings = readFoundationStrings(element);
+    const state = readComponentState(element, supplied.length > 0);
+    const panelId = useId();
+    const button = useRef<HTMLButtonElement>(null);
+
+    useEffect(() => setColumns(supplied), [suppliedKey]);
+    useValueOutput(bindingOutputs, visibleColumnIds(columns));
+
+    const apply = (next: ChooserColumn[]) => { setColumns(next); interactions?.onChange?.(); };
+    const close = (event: KeyboardEvent) => {
+        if (event.key !== 'Escape' || !open) return;
+        setOpen(false);
+        button.current?.focus();
+    };
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='column-chooser' state={state} skeleton={[50]}>
+            {state !== ComponentState.Loading && (
+                <div className='foundation-popover-host' onKeyDown={close}>
+                    <button ref={button} type='button' className='foundation-button' data-emphasis='secondary' aria-expanded={open} aria-controls={panelId} onClick={() => setOpen(!open)}>
+                        <FoundationIcon name='columns' />
+                        <span>{strings.columnsChoose}</span>
+                        <span className='foundation-count'>{formatText(strings.columnsShown, { shown: visibleColumnIds(columns).length, total: columns.length })}</span>
+                    </button>
+                    <div id={panelId} className='foundation-popover' hidden={!open}>
+                        <ul className='foundation-list' aria-label={strings.columnsChoose}>
+                            {columns.map((column, index) => (
+                                <li key={column.id} className='foundation-list-row'>
+                                    <label className='foundation-check'>
+                                        <input type='checkbox' checked={column.visible} disabled={column.locked} onChange={() => apply(toggleColumn(columns, index))} />
+                                        <span>{column.label}</span>
+                                        {column.locked && <span className='foundation-count'>({strings.columnsLocked})</span>}
+                                    </label>
+                                    <button type='button' className='foundation-icon-button' disabled={index === 0} aria-label={formatText(strings.columnsMoveUp, { name: column.label })} onClick={() => apply(moveColumn(columns, index, -1))}>
+                                        <FoundationIcon name='arrow-up' />
+                                    </button>
+                                    <button type='button' className='foundation-icon-button' disabled={index === columns.length - 1} aria-label={formatText(strings.columnsMoveDown, { name: column.label })} onClick={() => apply(moveColumn(columns, index, 1))}>
+                                        <FoundationIcon name='arrow-down' />
+                                    </button>
+                                </li>
+                            ))}
+                        </ul>
+                        <button type='button' className='foundation-link' onClick={() => apply(columns.map(column => ({ ...column, visible: true })))}>{strings.columnsReset}</button>
+                    </div>
+                </div>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/ComponentState.ts

@@ -0,0 +1,53 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ExternalComponent } from '@cratis/scene.model';
+
+/**
+ * The visual states every data-showing foundation component defines (spec Part B 1.4).
+ *
+ * A template is only worth choosing if it looks right in all of them: an application spends real time loading, empty, failing
+ * and not allowed, and a component that only draws its populated self has not been finished.
+ */
+export enum ComponentState {
+    /** The data is there and drawn. */
+    Ready = 'ready',
+
+    /** The data has not answered yet: a skeleton in the shape of the content, never a spinner alone. */
+    Loading = 'loading',
+
+    /** The data answered with nothing: an explanation and the primary action. */
+    Empty = 'empty',
+
+    /** The data could not be loaded: a message and a retry. */
+    Error = 'error',
+
+    /** The user may not see the data: what is missing, and nothing of the data. */
+    NoPermission = 'noPermission',
+
+    /** Some regions loaded and some failed: what loaded, plus which parts did not. */
+    Partial = 'partial',
+}
+
+/** Every state, in the order a preview or a story lists them. */
+export const componentStates: readonly ComponentState[] = Object.values(ComponentState);
+
+/**
+ * Reads the state a component is in from its properties.
+ *
+ * An explicit `state` property wins, which is how a preview forces a state. Otherwise the state follows the properties a bound
+ * query already publishes - the same `loading` and `error` the preview states use for tables - plus `forbidden` and
+ * `failedRegions`, and falls to Empty when the component has nothing to show.
+ *
+ * @param element The element being rendered.
+ * @param hasData Whether the component has anything to draw when it is ready.
+ */
+export function readComponentState(element: ExternalComponent, hasData: boolean): ComponentState {
+    const { state, forbidden, error, loading, failedRegions } = element.properties;
+    if (typeof state === 'string' && (componentStates as readonly string[]).includes(state)) return state as ComponentState;
+    if (forbidden === true) return ComponentState.NoPermission;
+    if (typeof error === 'string' && error.length > 0) return ComponentState.Error;
+    if (loading === true) return ComponentState.Loading;
+    if (Array.isArray(failedRegions) && failedRegions.length > 0) return ComponentState.Partial;
+    return hasData ? ComponentState.Ready : ComponentState.Empty;
+}

package/foundation/EmptyState.tsx

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { EmptyStateView } from './StateFrame';
+import { readFoundationStrings } from './foundationStrings';
+import { readLocale } from './formatting';
+
+/**
+ * The empty state as a component of its own: an icon, a headline, a hint and one primary action, embeddable in any region.
+ *
+ * Every other foundation component shows this same view when it has no data, so a screen reads the same wherever nothing is
+ * found. Placed on its own it is what a template puts in a region that has nothing to say yet. The action starts whatever the
+ * element's behaviors say, and honours the `actionPermission` rule, so an empty list never offers a creation the user may not do.
+ */
+export function EmptyState({ element, interactions }: RegisteredComponentProps) {
+    return (
+        <section className='foundation foundation-empty-state' data-scene-id={element.id} data-state='empty' lang={readLocale(element)}>
+            <EmptyStateView element={element} interactions={interactions} strings={readFoundationStrings(element)} />
+        </section>
+    );
+}

package/foundation/FilterBuilder.tsx

@@ -0,0 +1,144 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useEffect, useMemo, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { ComponentState, readComponentState } from './ComponentState';
+import { ActionButton } from './ActionButton';
+import {
+    FilterCondition, FilterField, emptyFilter, FilterFieldType, FilterGroup, countActiveConditions, filterOperators, maximumFilterDepth, newCondition,
+    normalizeFilter, readFilterFields, updateGroupAt, valuelessOperators,
+} from './filterModel';
+import { FoundationStrings, formatText, readFoundationStrings } from './foundationStrings';
+import { FoundationFrame } from './StateFrame';
+import { readPermissionRule } from './PermissionRule';
+
+const operatorText = (strings: FoundationStrings, operator: string): string => {
+    const names: Record<string, string> = {
+        contains: strings.opContains, equals: strings.opEquals, notEquals: strings.opNotEquals, startsWith: strings.opStartsWith, isEmpty: strings.opIsEmpty,
+        greater: strings.opGreater, greaterOrEqual: strings.opGreaterOrEqual, less: strings.opLess, lessOrEqual: strings.opLessOrEqual,
+        before: strings.opBefore, after: strings.opAfter, on: strings.opOn, is: strings.opIs, isNot: strings.opIsNot, true: strings.opTrue, false: strings.opFalse,
+    };
+    return names[operator] ?? operator;
+};
+
+interface GroupEditorProps {
+    group: FilterGroup;
+    path: number[];
+    fields: FilterField[];
+    strings: FoundationStrings;
+    locked: boolean;
+    change(path: number[], change: (group: FilterGroup) => FilterGroup): void;
+}
+
+function ValueInput({ field, condition, strings, label, disabled, onChange }: { field: FilterField | undefined; condition: FilterCondition; strings: FoundationStrings; label: string; disabled: boolean; onChange(value: string): void }) {
+    if (valuelessOperators.includes(condition.operator)) return undefined;
+
+    if (field?.type === FilterFieldType.Select) {
+        return (
+            <select aria-label={`${strings.filterValue}, ${label}`} value={condition.value} disabled={disabled} onChange={event => onChange(event.target.value)}>
+                <option value=''>—</option>
+                {field.options.map(option => <option key={option} value={option}>{option}</option>)}
+            </select>
+        );
+    }
+
+    return <input aria-label={`${strings.filterValue}, ${label}`} type={field?.type === FilterFieldType.Number ? 'number' : field?.type === FilterFieldType.Date ? 'date' : 'text'} value={condition.value} disabled={disabled} onChange={event => onChange(event.target.value)} />;
+}
+
+function GroupEditor({ group, path, fields, strings, locked, change }: GroupEditorProps) {
+    const label = path.length === 0 ? strings.filterMatchAll.replace(/ \(.*\)$/, '') : formatText(strings.filterGroup, { n: path.join('.') });
+    const depth = path.length + 1;
+
+    return (
+        <div className='foundation-filter-group' role='group' aria-label={path.length === 0 ? formatText(countActiveConditions(group) === 1 ? strings.filterSummaryOne : strings.filterSummary, { count: countActiveConditions(group) }) : label} data-depth={depth}>
+            <div className='foundation-filter-match'>
+                <select aria-label={strings.filterMatchAll} value={group.operator} disabled={locked} onChange={event => change(path, current => ({ ...current, operator: event.target.value === 'or' ? 'or' : 'and' }))}>
+                    <option value='and'>{strings.filterMatchAll}</option>
+                    <option value='or'>{strings.filterMatchAny}</option>
+                </select>
+                {path.length > 0 && !locked && (
+                    <button type='button' className='foundation-link' onClick={() => change(path.slice(0, -1), parent => ({ ...parent, groups: parent.groups.filter((_, index) => index !== path[path.length - 1]) }))}>{strings.filterRemoveGroup}</button>
+                )}
+            </div>
+            {group.conditions.map((condition, index) => {
+                const field = fields.find(candidate => candidate.name === condition.field);
+                const conditionLabel = formatText(strings.filterCondition, { n: index + 1 });
+                return (
+                    <div className='foundation-filter-row' role='group' aria-label={conditionLabel} key={index}>
+                        <select aria-label={`${strings.filterField}, ${conditionLabel}`} value={condition.field} disabled={locked}
+                            onChange={event => {
+                                const next = fields.find(candidate => candidate.name === event.target.value);
+                                change(path, current => ({ ...current, conditions: current.conditions.map((existing, position) => (position === index
+                                    ? { field: event.target.value, operator: next ? filterOperators[next.type][0] : existing.operator, value: '' } : existing)) }));
+                            }}>
+                            {fields.map(candidate => <option key={candidate.name} value={candidate.name}>{candidate.label}</option>)}
+                        </select>
+                        <select aria-label={`${strings.filterOperator}, ${conditionLabel}`} value={condition.operator} disabled={locked}
+                            onChange={event => change(path, current => ({ ...current, conditions: current.conditions.map((existing, position) => (position === index ? { ...existing, operator: event.target.value } : existing)) }))}>
+                            {filterOperators[field?.type ?? FilterFieldType.Text].map(operator => <option key={operator} value={operator}>{operatorText(strings, operator)}</option>)}
+                        </select>
+                        <ValueInput field={field} condition={condition} strings={strings} label={conditionLabel} disabled={locked}
+                            onChange={value => change(path, current => ({ ...current, conditions: current.conditions.map((existing, position) => (position === index ? { ...existing, value } : existing)) }))} />
+                        {!locked && (
+                            <button type='button' className='foundation-icon-button' aria-label={`${strings.filterRemove}, ${conditionLabel}`}
+                                onClick={() => change(path, current => ({ ...current, conditions: current.conditions.filter((_, position) => position !== index) }))}>×</button>
+                        )}
+                    </div>
+                );
+            })}
+            {group.groups.map((nested, index) => <GroupEditor key={index} group={nested} path={[...path, index]} fields={fields} strings={strings} locked={locked} change={change} />)}
+            {!locked && (
+                <div className='foundation-filter-actions'>
+                    <button type='button' className='foundation-link' onClick={() => change(path, current => ({ ...current, conditions: [...current.conditions, newCondition(fields)] }))}>{strings.filterAdd}</button>
+                    {depth < maximumFilterDepth && (
+                        <button type='button' className='foundation-link' onClick={() => change(path, current => ({ ...current, groups: [...current.groups, { operator: 'and', conditions: [newCondition(fields)], groups: [] }] }))}>{strings.filterAddGroup}</button>
+                    )}
+                </div>
+            )}
+        </div>
+    );
+}
+
+/**
+ * The `filterBuilder` component: field, operator and value conditions joined by AND or OR, in groups that nest up to three deep.
+ *
+ * The filter is the component's `value` output - `{ operator, conditions, groups }` - which a list screen binds its query to; the
+ * component itself filters nothing. `fields` describe what can be filtered (name, label, type, and options for a select), and
+ * the operators on offer follow each field's type. A filter bound in through `value` is read back as the user left it: conditions on
+ * fields that no longer exist are dropped rather than shown broken. The component is the filter panel of a list on a desktop and
+ * the body of the filter dialog on a phone.
+ */
+export function FilterBuilder({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const fields = useMemo(() => readFilterFields(element.properties.fields), [element.properties.fields]);
+    const supplied = useMemo(() => normalizeFilter(element.properties.filter, fields), [element.properties.filter, fields]);
+    const [filter, setFilter] = useState<FilterGroup>(supplied);
+    const strings = readFoundationStrings(element);
+    const suppliedKey = JSON.stringify(supplied);
+    const state = readComponentState(element, fields.length > 0);
+    const locked = readPermissionRule(element, 'editPermission') !== 'enabled';
+
+    useEffect(() => setFilter(supplied), [suppliedKey]);
+    useValueOutput(bindingOutputs, filter);
+
+    const change = (path: number[], apply: (group: FilterGroup) => FilterGroup) => {
+        const next = updateGroupAt(filter, path, apply);
+        setFilter(next);
+        interactions?.onChange?.();
+    };
+    const active = countActiveConditions(filter);
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='filter-builder' state={state} skeleton={[100, 100]}>
+            {state !== ComponentState.Loading && (
+                <>
+                    <GroupEditor group={filter} path={[]} fields={fields} strings={strings} locked={locked} change={change} />
+                    <div className='foundation-filter-footer'>
+                        <span className='foundation-filter-summary' aria-live='polite'>{active === 1 ? strings.filterSummaryOne : formatText(strings.filterSummary, { count: active })}</span>
+                        {active > 0 && !locked && <ActionButton emphasis='quiet' disabledReason={strings.disabledNoPermission} onClick={() => { setFilter(emptyFilter()); interactions?.onChange?.(); }}>{strings.filterClear}</ActionButton>}
+                    </div>
+                </>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/Foundation.stories.tsx

@@ -0,0 +1,46 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { ComponentName } from '../ComponentName';
+import { FoundationStates } from './FoundationStates';
+
+/**
+ * The foundation components (spec Part B 4), each in every standard state - ready, loading, empty, error, no permission and
+ * partial - in the light and the dark theme. Each component also has a right-to-left story.
+ */
+const meta = {
+    title: 'Blueprint/Foundation components',
+    component: FoundationStates,
+    parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof FoundationStates>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const EmptyStateLight: Story = { args: { component: ComponentName.EmptyState, theme: 'light' } };
+export const EmptyStateDark: Story = { args: { component: ComponentName.EmptyState, theme: 'dark' } };
+export const StatCardLight: Story = { args: { component: ComponentName.StatCard, theme: 'light' } };
+export const StatCardDark: Story = { args: { component: ComponentName.StatCard, theme: 'dark' } };
+export const StatCardRightToLeft: Story = { args: { component: ComponentName.StatCard, theme: 'light', rightToLeft: true, properties: { label: 'خط الأنابيب', locale: 'ar-EG' } } };
+export const TrendChipLight: Story = { args: { component: ComponentName.TrendChip, theme: 'light' } };
+export const TrendChipDark: Story = { args: { component: ComponentName.TrendChip, theme: 'dark' } };
+export const StatusChipLight: Story = { args: { component: ComponentName.StatusChip, theme: 'light' } };
+export const StatusChipDark: Story = { args: { component: ComponentName.StatusChip, theme: 'dark' } };
+export const ChartLineLight: Story = { args: { component: ComponentName.ChartWrapper, theme: 'light' } };
+export const ChartLineDark: Story = { args: { component: ComponentName.ChartWrapper, theme: 'dark' } };
+export const ChartBarLight: Story = { args: { component: ComponentName.ChartWrapper, theme: 'light', properties: { kind: 'bar' } } };
+export const ChartBarDark: Story = { args: { component: ComponentName.ChartWrapper, theme: 'dark', properties: { kind: 'bar' } } };
+export const ChartStackedLight: Story = { args: { component: ComponentName.ChartWrapper, theme: 'light', properties: { kind: 'stacked' } } };
+export const ChartStackedDark: Story = { args: { component: ComponentName.ChartWrapper, theme: 'dark', properties: { kind: 'stacked' } } };
+export const ChartDonutLight: Story = { args: { component: ComponentName.ChartWrapper, theme: 'light', properties: { kind: 'donut' } } };
+export const ChartDonutDark: Story = { args: { component: ComponentName.ChartWrapper, theme: 'dark', properties: { kind: 'donut' } } };
+export const ChartFunnelLight: Story = { args: { component: ComponentName.ChartWrapper, theme: 'light', properties: { kind: 'funnel', categories: ['Leads', 'Qualified', 'Proposal', 'Won'], series: [{ name: 'Deals', values: [400, 220, 90, 40] }] } } };
+export const ChartFunnelDark: Story = { args: { component: ComponentName.ChartWrapper, theme: 'dark', properties: { kind: 'funnel', categories: ['Leads', 'Qualified', 'Proposal', 'Won'], series: [{ name: 'Deals', values: [400, 220, 90, 40] }] } } };
+export const FilterBuilderLight: Story = { args: { component: ComponentName.FilterBuilder, theme: 'light' } };
+export const FilterBuilderDark: Story = { args: { component: ComponentName.FilterBuilder, theme: 'dark' } };
+export const ColumnChooserLight: Story = { args: { component: ComponentName.ColumnChooser, theme: 'light' } };
+export const ColumnChooserDark: Story = { args: { component: ComponentName.ColumnChooser, theme: 'dark' } };
+export const SavedViewsMenuLight: Story = { args: { component: ComponentName.SavedViewsMenu, theme: 'light' } };
+export const SavedViewsMenuDark: Story = { args: { component: ComponentName.SavedViewsMenu, theme: 'dark' } };