@cratis/scene.blueprint.default 4.30.0 → 4.32.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/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/Foundation.stories.tsx

@@ -0,0 +1,30 @@
+// 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' } };

package/foundation/FoundationIcon.tsx

@@ -0,0 +1,49 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The icons the foundation components draw themselves, so none of them depends on an icon font being loaded. */
+export type FoundationIconName =
+    | 'check' | 'close' | 'arrow-up' | 'arrow-down' | 'minus' | 'alert' | 'info' | 'lock' | 'clock' | 'inbox' | 'refresh'
+    | 'plus' | 'chevron-right' | 'chevron-down' | 'upload' | 'file' | 'user' | 'columns' | 'filter' | 'star' | 'circle';
+
+const paths: Record<FoundationIconName, string> = {
+    check: 'M5 13l4 4L19 7',
+    close: 'M6 6l12 12M18 6L6 18',
+    'arrow-up': 'M12 19V5M5 12l7-7 7 7',
+    'arrow-down': 'M12 5v14M5 12l7 7 7-7',
+    minus: 'M5 12h14',
+    alert: 'M12 8v5M12 16.5v.5M10.3 3.9L2.5 17.5A2 2 0 004.2 20.5h15.6a2 2 0 001.7-3L13.7 3.9a2 2 0 00-3.4 0z',
+    info: 'M12 11v6M12 7.5v.5M12 21a9 9 0 100-18 9 9 0 000 18z',
+    lock: 'M7 11V8a5 5 0 0110 0v3M6 11h12a1 1 0 011 1v8a1 1 0 01-1 1H6a1 1 0 01-1-1v-8a1 1 0 011-1z',
+    clock: 'M12 7v5l3 2M12 21a9 9 0 100-18 9 9 0 000 18z',
+    inbox: 'M3 13l3-8h12l3 8M3 13v6a1 1 0 001 1h16a1 1 0 001-1v-6M3 13h5l1 3h6l1-3h5',
+    refresh: 'M20 11a8 8 0 10-2.3 6.3M20 4v7h-7',
+    plus: 'M12 5v14M5 12h14',
+    'chevron-right': 'M9 5l7 7-7 7',
+    'chevron-down': 'M5 9l7 7 7-7',
+    upload: 'M12 16V4M7 9l5-5 5 5M4 17v2a1 1 0 001 1h14a1 1 0 001-1v-2',
+    file: 'M14 3H7a1 1 0 00-1 1v16a1 1 0 001 1h10a1 1 0 001-1V7l-4-4zM14 3v4h4',
+    user: 'M12 12a4 4 0 100-8 4 4 0 000 8zM4 21a8 8 0 0116 0',
+    columns: 'M4 5h16v14H4zM9.5 5v14M14.5 5v14',
+    filter: 'M4 5h16l-6 8v6l-4-2v-4L4 5z',
+    star: 'M12 3l2.7 5.6 6.1.9-4.4 4.3 1 6.1L12 17l-5.4 2.9 1-6.1L3.2 9.5l6.1-.9L12 3z',
+    circle: 'M12 20a8 8 0 100-16 8 8 0 000 16z',
+};
+
+/** Whether a name is one of the icons drawn here. */
+export function isFoundationIcon(name: string): name is FoundationIconName {
+    return name in paths;
+}
+
+/**
+ * One icon. It is decorative unless given a label: the meaning an icon carries is always repeated in text, so no status is
+ * conveyed by color or shape alone (WCAG 1.4.1).
+ */
+export function FoundationIcon({ name, label }: { name: FoundationIconName; label?: string }) {
+    return (
+        <svg className='foundation-icon' viewBox='0 0 24 24' width='1em' height='1em' fill='none' stroke='currentColor' strokeWidth='2'
+            strokeLinecap='round' strokeLinejoin='round' aria-hidden={label ? undefined : true} role={label ? 'img' : undefined} aria-label={label}>
+            <path d={paths[name]} />
+        </svg>
+    );
+}

package/foundation/FoundationStates.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 { componentRegistryKey, SceneThemeProvider } from '@cratis/scene.react';
+import { defaultBlueprintComponents } from '../defaultBlueprintComponents';
+import { defaultBlueprintName } from '../packageName';
+import { darkTheme, lightTheme } from '../themes';
+import { ComponentState, componentStates } from './ComponentState';
+import { foundationElement, foundationSamples } from './foundationSamples';
+
+export interface FoundationStatesProps {
+    /** The bare name of the foundation component. */
+    component: string;
+
+    /** The theme the states are drawn in. */
+    theme: 'light' | 'dark';
+
+    /** Properties to lay over the sample, to show a variant. */
+    properties?: Record<string, unknown>;
+
+    /** Whether the page reads right to left. */
+    rightToLeft?: boolean;
+}
+
+/**
+ * Every standard state of one foundation component side by side in one theme: the preview of spec Part B 6 ("all standard states
+ * implemented and previewable"), used by the stories and by the gallery.
+ */
+export function FoundationStates({ component, theme, properties, rightToLeft }: FoundationStatesProps) {
+    const Component = defaultBlueprintComponents[componentRegistryKey(defaultBlueprintName, component)];
+    const sample = foundationSamples[component];
+    const states = sample?.stateful ? componentStates : [ComponentState.Ready];
+
+    return (
+        <SceneThemeProvider theme={theme === 'dark' ? darkTheme : lightTheme}>
+            <div dir={rightToLeft ? 'rtl' : 'ltr'} className='foundation-states' style={{ display: 'grid', gap: '1rem', padding: '1rem', gridTemplateColumns: 'repeat(auto-fill, minmax(18rem, 1fr))', background: 'var(--scene-surface-background)', color: 'var(--scene-text-color)' }}>
+                {states.map(state => (
+                    <figure key={state} style={{ margin: 0 }}>
+                        <figcaption style={{ fontSize: '0.75rem', textTransform: 'uppercase', marginBlockEnd: '0.5rem' }}>{state}</figcaption>
+                        <Component element={foundationElement(component, { ...sample?.properties, ...properties }, state === ComponentState.Ready ? undefined : state)} slots={{}} />
+                    </figure>
+                ))}
+            </div>
+        </SceneThemeProvider>
+    );
+}

package/foundation/PermissionRule.ts

@@ -0,0 +1,26 @@
+// 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';
+
+/**
+ * What an action control does when the user lacks the permission it needs (spec Part B 1.5): it is shown and works, shown and
+ * refuses, or not shown. A template never assumes a role, so every action declares one of these and the host's permission
+ * evaluation sets it.
+ */
+export enum PermissionRule {
+    /** The control works. */
+    Enabled = 'enabled',
+
+    /** The control is shown but cannot be used, and says why. */
+    Disabled = 'disabled',
+
+    /** The control is not rendered. */
+    Hidden = 'hidden',
+}
+
+/** Reads a permission rule from a property, defaulting to Enabled for anything that is not a rule. */
+export function readPermissionRule(element: ExternalComponent, property = 'permission'): PermissionRule {
+    const value = element.properties[property];
+    return value === PermissionRule.Disabled || value === PermissionRule.Hidden ? value : PermissionRule.Enabled;
+}

package/foundation/StatCard.tsx

@@ -0,0 +1,44 @@
+// 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 { ComponentState, readComponentState } from './ComponentState';
+import { FoundationFrame } from './StateFrame';
+import { TrendChipView } from './TrendChip';
+import { formatNumber, readLocale, readNumberFormat } from './formatting';
+import { readFoundationStrings } from './foundationStrings';
+import { readOptionalString, readString } from '../shell/elementProperties';
+
+/**
+ * The `statCard` component: one key figure with its label, its trend and what the trend is compared to - the unit of a dashboard's
+ * `kpis` slot.
+ *
+ * The value is a bound number, never embedded in the component (a figure is data, not design); it is formatted for the locale as
+ * a number, currency, percent or compact. With no value the card is empty, and it shows all five standard states
+ * independently of its neighbours, so a dashboard whose one query failed still shows the other cards.
+ */
+export function StatCard({ element, interactions }: RegisteredComponentProps) {
+    const value = element.properties.value;
+    const hasValue = typeof value === 'number';
+    const state = readComponentState(element, hasValue);
+    const locale = readLocale(element);
+    const label = readString(element, 'label');
+    const change = element.properties.change;
+    const currency = readOptionalString(element, 'currency');
+
+    return (
+        <FoundationFrame element={element} interactions={interactions}
+            name='stat-card' state={state} skeleton={[40, 70, 30]}>
+            {state !== ComponentState.Loading && (
+                <>
+                    <h3 className='foundation-stat-label'>{label}</h3>
+                    <p className='foundation-stat-value'>{hasValue ? formatNumber(value, locale, readNumberFormat(element), currency, typeof element.properties.fractionDigits === 'number' ? element.properties.fractionDigits : undefined) : ''}</p>
+                    {typeof change === 'number' && (
+                        <TrendChipView change={change} locale={locale} goodDirection={element.properties.goodDirection === 'down' ? 'down' : 'up'}
+                            comparison={readOptionalString(element, 'comparison')} strings={readFoundationStrings(element)} />
+                    )}
+                </>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/StateFrame.tsx

@@ -0,0 +1,126 @@
+// 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 { ExternalComponent } from '@cratis/scene.model';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readOptionalString, readStrings } from '../shell/elementProperties';
+import { ActionButton } from './ActionButton';
+import { ComponentState } from './ComponentState';
+import { FoundationIcon, FoundationIconName } from './FoundationIcon';
+import { FoundationStrings, formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+import { readLocale } from './formatting';
+
+export interface FoundationFrameProps extends Pick<RegisteredComponentProps, 'element' | 'interactions'> {
+    /** The component's own class, added after `foundation`. */
+    name: string;
+
+    /** The state the component is in; compute it with `readComponentState`. */
+    state: ComponentState;
+
+    /** The shape of the skeleton, as the width of each block in percent; the skeleton keeps the footprint of the content. */
+    skeleton?: number[];
+
+    /** What the component draws when it is ready or partial. */
+    children?: ReactNode;
+}
+
+/** The accessible name of a region, from the element's `label` property. */
+function regionLabel(element: ExternalComponent): string | undefined {
+    return readOptionalString(element, 'label') ?? readOptionalString(element, 'title');
+}
+
+/**
+ * The root every foundation component renders, and the five standard states of spec Part B 1.4 in one place:
+ * a skeleton while loading (never a spinner alone), an explanation with the primary action when empty, a message with a
+ * retry on error, what is missing - and nothing of the data - when the user is not allowed, and the loaded part with a
+ * note naming what failed when only some regions did.
+ *
+ * The region carries an ARIA landmark role when it has a label, a `dir` is left to the document so right-to-left is
+ * inherited, and every piece of text comes from the strings table.
+ */
+export function FoundationFrame({ element, interactions, name, state, skeleton = [60, 100, 80], children }: FoundationFrameProps) {
+    const strings = readFoundationStrings(element);
+    const label = regionLabel(element);
+    const density = element.properties.density === 'compact' ? 'compact' : 'comfortable';
+
+    return (
+        <section className={`foundation foundation-${name}`} data-scene-id={element.id} data-state={state} data-density={density}
+            lang={readLocale(element)} role={label ? 'region' : undefined} aria-label={label} aria-busy={state === ComponentState.Loading || undefined}>
+            {renderState(element, interactions, strings, state, skeleton, children)}
+        </section>
+    );
+}
+
+function renderState(element: ExternalComponent, interactions: RegisteredComponentProps['interactions'], strings: FoundationStrings, state: ComponentState, skeleton: number[], children: ReactNode) {
+    switch (state) {
+        case ComponentState.Loading:
+            return (
+                <div className='foundation-skeleton' role='status'>
+                    <span className='foundation-visually-hidden'>{strings.loading}</span>
+                    {skeleton.map((width, index) => <span key={index} className='foundation-skeleton-block' style={{ width: `${width}%` }} aria-hidden='true' />)}
+                </div>
+            );
+        case ComponentState.Empty:
+            return <EmptyStateView element={element} interactions={interactions} strings={strings} />;
+        case ComponentState.Error:
+            return (
+                <div className='foundation-message' data-tone='danger' role='alert'>
+                    <FoundationIcon name='alert' />
+                    <div className='foundation-message-text'>
+                        <strong>{strings.errorHeadline}</strong>
+                        <span>{typeof element.properties.error === 'string' && element.properties.error.length > 0 ? element.properties.error : strings.errorHint}</span>
+                    </div>
+                    <ActionButton emphasis='secondary' disabledReason={strings.disabledNoPermission} onClick={interactions?.onClick}>{strings.retry}</ActionButton>
+                </div>
+            );
+        case ComponentState.NoPermission: {
+            const subject = readOptionalString(element, 'permissionSubject') ?? strings.noPermissionSubject;
+            return (
+                <div className='foundation-message' data-tone='neutral' role='status'>
+                    <FoundationIcon name='lock' />
+                    <div className='foundation-message-text'>
+                        <strong>{strings.noPermissionHeadline}</strong>
+                        <span>{formatText(strings.noPermissionHint, { subject })}</span>
+                    </div>
+                </div>
+            );
+        }
+
+        case ComponentState.Partial:
+            return (
+                <>
+                    <div className='foundation-message' data-tone='warning' role='status'>
+                        <FoundationIcon name='alert' />
+                        <div className='foundation-message-text'>
+                            <strong>{strings.partialHeadline}</strong>
+                            {readStrings(element, 'failedRegions').length > 0 && <span>{formatText(strings.partialHint, { regions: readStrings(element, 'failedRegions').join(', ') })}</span>}
+                        </div>
+                        <ActionButton emphasis='secondary' disabledReason={strings.disabledNoPermission} onClick={interactions?.onClick}>{strings.retry}</ActionButton>
+                    </div>
+                    {children}
+                </>
+            );
+        default:
+            return <>{children}</>;
+    }
+}
+
+/** What an empty region says: an icon, a headline, a hint and the primary action, with the action's permission rule applied. */
+export function EmptyStateView({ element, interactions, strings }: Pick<FoundationFrameProps, 'element' | 'interactions'> & { strings: FoundationStrings }) {
+    const icon = (readOptionalString(element, 'emptyIcon') ?? readOptionalString(element, 'icon')) as FoundationIconName | undefined;
+    const actionLabel = readOptionalString(element, 'emptyActionLabel') ?? readOptionalString(element, 'actionLabel');
+
+    return (
+        <div className='foundation-empty' role='status'>
+            <span className='foundation-empty-icon'><FoundationIcon name={icon ?? 'inbox'} /></span>
+            <strong className='foundation-empty-headline'>{readOptionalString(element, 'emptyHeadline') ?? readOptionalString(element, 'headline') ?? strings.emptyHeadline}</strong>
+            <span className='foundation-empty-hint'>{readOptionalString(element, 'emptyHint') ?? readOptionalString(element, 'hint') ?? strings.emptyHint}</span>
+            {actionLabel && (
+                <ActionButton rule={readPermissionRule(element, 'actionPermission')} disabledReason={strings.disabledNoPermission} onClick={interactions?.onClick}>{actionLabel}</ActionButton>
+            )}
+        </div>
+    );
+}
+

package/foundation/StatusChip.tsx

@@ -0,0 +1,51 @@
+// 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 { readFoundationStrings } from './foundationStrings';
+import { FoundationIcon, FoundationIconName } from './FoundationIcon';
+import { readOptionalString, readString } from '../shell/elementProperties';
+
+/** The semantic tone of a status. */
+export enum StatusTone {
+    Success = 'success',
+    Warning = 'warning',
+    Danger = 'danger',
+    Info = 'info',
+    Neutral = 'neutral',
+}
+
+/** The icon each tone gets, so a status is told by shape as well as color (WCAG 1.4.1). */
+export const statusToneIcons: Record<StatusTone, FoundationIconName> = {
+    [StatusTone.Success]: 'check',
+    [StatusTone.Warning]: 'alert',
+    [StatusTone.Danger]: 'close',
+    [StatusTone.Info]: 'info',
+    [StatusTone.Neutral]: 'circle',
+};
+
+/** Reads a tone, defaulting to Neutral. */
+export function readStatusTone(value: unknown): StatusTone {
+    return (Object.values(StatusTone) as string[]).includes(value as string) ? (value as StatusTone) : StatusTone.Neutral;
+}
+
+/**
+ * The `statusChip` component: a status as a semantic color, an icon and its text.
+ *
+ * The text is always shown - the status of a record is never only a colored dot - and the tone picks the icon and the color from
+ * the theme's status tokens. A status the application names ("Awaiting approval") is its own `status` text; `tone` maps it onto
+ * one of the five tones.
+ */
+export function StatusChip({ element }: RegisteredComponentProps) {
+    const tone = readStatusTone(element.properties.tone);
+    const strings = readFoundationStrings(element);
+    const fallback = { success: strings.statusSuccess, warning: strings.statusWarning, danger: strings.statusDanger, info: strings.statusInfo, neutral: strings.statusNeutral }[tone];
+    const text = readString(element, 'status', readOptionalString(element, 'label') ?? fallback);
+
+    return (
+        <span className='foundation foundation-chip foundation-status-chip' data-scene-id={element.id} data-tone={tone}>
+            <FoundationIcon name={statusToneIcons[tone]} />
+            <span>{text}</span>
+        </span>
+    );
+}

package/foundation/TrendChip.tsx

@@ -0,0 +1,78 @@
+// 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 { FoundationIcon } from './FoundationIcon';
+import { formatNumber, NumberFormat, readLocale } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readOptionalString } from '../shell/elementProperties';
+
+/** The direction a measure moved. */
+export type TrendDirection = 'up' | 'down' | 'flat';
+
+/** Whether a movement is good, bad or neither, which is independent of whether the number rose: falling response time is good. */
+export type TrendOutcome = 'good' | 'bad' | 'neutral';
+
+/** The direction a change moved in. */
+export function trendDirection(change: number): TrendDirection {
+    return change > 0 ? 'up' : change < 0 ? 'down' : 'flat';
+}
+
+/** Whether a movement is good for a measure, given which direction is the good one. */
+export function trendOutcome(direction: TrendDirection, goodDirection: 'up' | 'down'): TrendOutcome {
+    return direction === 'flat' ? 'neutral' : direction === goodDirection ? 'good' : 'bad';
+}
+
+/** The tone each outcome is drawn in. */
+const tones: Record<TrendOutcome, string> = { good: 'success', bad: 'danger', neutral: 'neutral' };
+
+/** The props of a trend chip drawn directly, as the stat card does. */
+export interface TrendChipViewProps {
+    change: number;
+    locale: string;
+    goodDirection?: 'up' | 'down';
+    comparison?: string;
+    format?: NumberFormat;
+    strings: ReturnType<typeof readFoundationStrings>;
+}
+
+/**
+ * A change, drawn as an arrow, the change and what it is compared to.
+ *
+ * Color says whether the movement is good, but never alone: the arrow gives direction and a visually hidden sentence
+ * says all of it ("up 12.5% compared to last month"), so the chip reads the same without color.
+ */
+export function TrendChipView({ change, locale, goodDirection = 'up', comparison, format = NumberFormat.Percent, strings }: TrendChipViewProps) {
+    const direction = trendDirection(change);
+    const outcome = trendOutcome(direction, goodDirection);
+    const magnitude = formatNumber(Math.abs(change), locale, format);
+    const spoken = direction === 'flat' ? strings.trendFlat : formatText(direction === 'up' ? strings.trendUp : strings.trendDown, { value: magnitude });
+
+    return (
+        <span className='foundation-chip foundation-trend' data-tone={tones[outcome]} data-direction={direction}>
+            <FoundationIcon name={direction === 'up' ? 'arrow-up' : direction === 'down' ? 'arrow-down' : 'minus'} />
+            <span aria-hidden='true'>{direction === 'flat' ? magnitude : magnitude}</span>
+            <span className='foundation-visually-hidden'>{spoken}{comparison ? ` ${formatText(strings.trendComparison, { period: comparison })}` : ''}</span>
+            {comparison && <span className='foundation-trend-comparison' aria-hidden='true'>{formatText(strings.trendComparison, { period: comparison })}</span>}
+        </span>
+    );
+}
+
+/**
+ * The `trendChip` component: a change with its direction, whether that is good, and what it is compared to.
+ *
+ * `change` is the movement as a number (a percentage by default), `goodDirection` says which way is good, and `comparison` names
+ * the period. Without a number the chip is empty, and then it draws nothing rather than an invented zero.
+ */
+export function TrendChip({ element }: RegisteredComponentProps) {
+    const change = element.properties.change;
+    if (typeof change !== 'number') return undefined;
+
+    return (
+        <span className='foundation foundation-trend-chip' data-scene-id={element.id}>
+            <TrendChipView change={change} locale={readLocale(element)} goodDirection={element.properties.goodDirection === 'down' ? 'down' : 'up'}
+                comparison={readOptionalString(element, 'comparison')} strings={readFoundationStrings(element)}
+                {...(typeof element.properties.format === 'string' && (Object.values(NumberFormat) as string[]).includes(element.properties.format) ? { format: element.properties.format as NumberFormat } : {})} />
+        </span>
+    );
+}

package/foundation/formatting.ts

@@ -0,0 +1,69 @@
+// 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';
+
+/** How a number is presented. */
+export enum NumberFormat {
+    Number = 'number',
+    Currency = 'currency',
+    Percent = 'percent',
+    Compact = 'compact',
+}
+
+/**
+ * The locale a component formats dates, numbers and currency in: the element's `locale`, else the document language, else the
+ * runtime's. Formatting never goes through a fixed locale, so the same screen reads correctly in every one.
+ */
+export function readLocale(element: ExternalComponent): string {
+    const supplied = element.properties.locale;
+    if (typeof supplied === 'string' && supplied.length > 0) return supplied;
+    if (typeof document !== 'undefined' && document.documentElement.lang) return document.documentElement.lang;
+    return typeof navigator !== 'undefined' && navigator.language ? navigator.language : 'en';
+}
+
+/** Whether the locale reads right to left, so a component can mirror what direction-sensitive CSS cannot. */
+export function isRightToLeft(locale: string): boolean {
+    try {
+        const info = new Intl.Locale(locale) as Intl.Locale & { getTextInfo?: () => { direction: string }; textInfo?: { direction: string } };
+        const direction = info.getTextInfo?.().direction ?? info.textInfo?.direction;
+        return direction === 'rtl';
+    } catch {
+        return false;
+    }
+}
+
+/** Formats a number for a locale, as a plain number, currency, percent (the value is the percentage, 12.5 is 12.5%) or compact. */
+export function formatNumber(value: number, locale: string, format: NumberFormat = NumberFormat.Number, currency = 'USD', maximumFractionDigits?: number): string {
+    try {
+        switch (format) {
+            case NumberFormat.Currency:
+                return new Intl.NumberFormat(locale, { style: 'currency', currency, ...(maximumFractionDigits === undefined ? {} : { maximumFractionDigits }) }).format(value);
+            case NumberFormat.Percent:
+                return new Intl.NumberFormat(locale, { style: 'percent', maximumFractionDigits: maximumFractionDigits ?? 1 }).format(value / 100);
+            case NumberFormat.Compact:
+                return new Intl.NumberFormat(locale, { notation: 'compact', maximumFractionDigits: maximumFractionDigits ?? 1 }).format(value);
+            default:
+                return new Intl.NumberFormat(locale, { maximumFractionDigits: maximumFractionDigits ?? 2 }).format(value);
+        }
+    } catch {
+        return String(value);
+    }
+}
+
+/** Reads a number format name, defaulting to a plain number. */
+export function readNumberFormat(element: ExternalComponent, property = 'format'): NumberFormat {
+    const value = element.properties[property];
+    return (Object.values(NumberFormat) as string[]).includes(value as string) ? (value as NumberFormat) : NumberFormat.Number;
+}
+
+/** Formats a date or an ISO 8601 date-time for a locale; a value that is not a date is returned as it was written. */
+export function formatDate(value: unknown, locale: string, withTime = false): string {
+    const date = value instanceof Date ? value : typeof value === 'string' || typeof value === 'number' ? new Date(value) : undefined;
+    if (!date || Number.isNaN(date.getTime())) return typeof value === 'string' ? value : '';
+    try {
+        return new Intl.DateTimeFormat(locale, withTime ? { dateStyle: 'medium', timeStyle: 'short' } : { dateStyle: 'medium' }).format(date);
+    } catch {
+        return date.toISOString();
+    }
+}