@cratis/scene.blueprint.default 4.31.0 → 4.33.0

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/SavedViewsMenu.tsx

@@ -0,0 +1,94 @@
+// 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 { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon } from './FoundationIcon';
+import { readFoundationStrings } from './foundationStrings';
+import { PermissionRule, readPermissionRule } from './PermissionRule';
+import { FoundationFrame } from './StateFrame';
+import { readOptionalString } from '../shell/elementProperties';
+import { readViews } from './viewModel';
+
+/** The output a menu action is published under: `save` or `manage`, which the host acts on. */
+export const savedViewActionOutput = 'action';
+
+/**
+ * The `savedViewsMenu` component: a list's saved views as a menu button, with the current view as its label.
+ *
+ * `views` are the choices (id, label, description) and `activeView` the one in force. Choosing a view publishes its id as the `value`
+ * output and runs the behaviors attached to the element, so a screen binds its query to the view. The menu follows the ARIA menu
+ * pattern: arrows, Home and End move, Enter chooses, Escape closes and returns focus to the button. "Save current view" and
+ * "Manage views" publish `save` or `manage` on the `action` output, and each honours its own permission rule (`savePermission`,
+ * `managePermission`): hidden, or disabled with the reason.
+ */
+export function SavedViewsMenu({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const views = useMemo(() => readViews(element.properties.views), [element.properties.views]);
+    const suppliedActive = readOptionalString(element, 'activeView') ?? views[0]?.id;
+    const [active, setActive] = useState<string | undefined>(suppliedActive);
+    const [open, setOpen] = useState(false);
+    const strings = readFoundationStrings(element);
+    const state = readComponentState(element, views.length > 0);
+    const menuId = useId();
+    const button = useRef<HTMLButtonElement>(null);
+    const menu = useRef<HTMLDivElement>(null);
+    const rules = { save: readPermissionRule(element, 'savePermission'), manage: readPermissionRule(element, 'managePermission') };
+
+    useEffect(() => setActive(suppliedActive), [suppliedActive]);
+    useValueOutput(bindingOutputs, active);
+    useEffect(() => { if (open) menu.current?.querySelector<HTMLElement>('[role^="menuitem"]:not([aria-disabled="true"])')?.focus(); }, [open]);
+
+    const items = () => Array.from(menu.current?.querySelectorAll<HTMLElement>('[role^="menuitem"]:not([aria-disabled="true"])') ?? []);
+    const move = (event: KeyboardEvent) => {
+        const entries = items();
+        const index = entries.indexOf(document.activeElement as HTMLElement);
+        const target = event.key === 'ArrowDown' ? (index + 1) % entries.length : event.key === 'ArrowUp' ? (index - 1 + entries.length) % entries.length
+            : event.key === 'Home' ? 0 : event.key === 'End' ? entries.length - 1 : -1;
+
+        if (target >= 0) { event.preventDefault(); entries[target]?.focus(); }
+        if (event.key === 'Escape') { setOpen(false); button.current?.focus(); }
+        if (event.key === 'Tab') setOpen(false);
+    };
+    const choose = (id: string) => { setActive(id); setOpen(false); button.current?.focus(); interactions?.onSelect?.(); };
+    const run = (action: 'save' | 'manage') => { bindingOutputs?.setOutput(savedViewActionOutput, action); setOpen(false); button.current?.focus(); interactions?.onClick?.({ stopPropagation: () => undefined }); };
+    const label = views.find(view => view.id === active)?.label ?? strings.viewsDefault;
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='saved-views' state={state} skeleton={[45]}>
+            {state !== ComponentState.Loading && (
+                <div className='foundation-popover-host'>
+                    <button ref={button} type='button' className='foundation-button' data-emphasis='secondary' aria-haspopup='menu' aria-expanded={open} aria-controls={menuId}
+                        onClick={() => setOpen(!open)} onKeyDown={event => { if (event.key === 'ArrowDown' && !open) { event.preventDefault(); setOpen(true); } }}>
+                        <span className='foundation-visually-hidden'>{`${strings.viewsLabel}: `}</span>
+                        <span>{label}</span>
+                        <FoundationIcon name='chevron-down' />
+                    </button>
+                    <div id={menuId} ref={menu} className='foundation-popover' role='menu' aria-label={strings.viewsLabel} hidden={!open} onKeyDown={move}>
+                        {views.length === 0 && <span className='foundation-count'>{strings.viewsNone}</span>}
+                        {views.map(view => (
+                            <button key={view.id} type='button' role='menuitemradio' aria-checked={view.id === active} className='foundation-menu-item' tabIndex={-1} onClick={() => choose(view.id)}>
+                                <span className='foundation-menu-check'>{view.id === active && <FoundationIcon name='check' />}</span>
+                                <span>{view.label}</span>
+                                {view.description && <span className='foundation-count'>{view.description}</span>}
+                            </button>
+                        ))}
+                        {(rules.save !== PermissionRule.Hidden || rules.manage !== PermissionRule.Hidden) && <hr className='foundation-separator' />}
+                        {rules.save !== PermissionRule.Hidden && (
+                            <button type='button' role='menuitem' className='foundation-menu-item' tabIndex={-1} aria-disabled={rules.save === PermissionRule.Disabled || undefined}
+                                title={rules.save === PermissionRule.Disabled ? strings.disabledNoPermission : undefined} onClick={rules.save === PermissionRule.Enabled ? () => run('save') : undefined}>
+                                <span className='foundation-menu-check' /><span>{strings.viewsSave}</span>
+                            </button>
+                        )}
+                        {rules.manage !== PermissionRule.Hidden && (
+                            <button type='button' role='menuitem' className='foundation-menu-item' tabIndex={-1} aria-disabled={rules.manage === PermissionRule.Disabled || undefined}
+                                title={rules.manage === PermissionRule.Disabled ? strings.disabledNoPermission : undefined} onClick={rules.manage === PermissionRule.Enabled ? () => run('manage') : undefined}>
+                                <span className='foundation-menu-check' /><span>{strings.viewsManage}</span>
+                            </button>
+                        )}
+                    </div>
+                </div>
+            )}
+        </FoundationFrame>
+    );
+}

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/chartGeometry.ts

@@ -0,0 +1,108 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The kinds of chart the wrapper draws (spec Part B 2.3: line, bar, stacked, donut, funnel). */
+export enum ChartKind {
+    Line = 'line',
+    Bar = 'bar',
+    Stacked = 'stacked',
+    Donut = 'donut',
+    Funnel = 'funnel',
+}
+
+/** One named series of values, one per category. */
+export interface ChartSeries {
+    name: string;
+    values: number[];
+}
+
+/** A rounded-up axis maximum and the tick values below it, so an axis reads 0, 25, 50, 75, 100 and not 0, 23.4, 46.8. */
+export interface ChartScale {
+    maximum: number;
+    ticks: number[];
+}
+
+/** Builds a scale from zero to a rounded-up maximum of the values, in about `target` steps. */
+export function niceScale(maximum: number, target = 4): ChartScale {
+    if (!Number.isFinite(maximum) || maximum <= 0) return { maximum: 1, ticks: [0, 1] };
+
+    const rough = maximum / target;
+    const magnitude = 10 ** Math.floor(Math.log10(rough));
+    const residual = rough / magnitude;
+    const step = (residual <= 1 ? 1 : residual <= 2 ? 2 : residual <= 5 ? 5 : 10) * magnitude;
+    const top = Math.ceil(maximum / step) * step;
+    const ticks: number[] = [];
+    for (let tick = 0; tick <= top + step / 2; tick += step) ticks.push(Number(tick.toFixed(10)));
+    return { maximum: top, ticks };
+}
+
+/** Reads series out of a property value, dropping anything that is not a named list of numbers, so a half-bound chart draws what it has. */
+export function readSeries(value: unknown): ChartSeries[] {
+    if (!Array.isArray(value)) return [];
+
+    return value.flatMap((entry): ChartSeries[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { name, values } = entry as Record<string, unknown>;
+        if (typeof name !== 'string' || !Array.isArray(values)) return [];
+        return [{ name, values: values.map(item => (typeof item === 'number' && Number.isFinite(item) ? item : 0)) }];
+    });
+}
+
+/** The extent of the values a chart of this kind has to fit: stacked series add up, the others are compared one by one. */
+export function dataMaximum(kind: ChartKind, series: ChartSeries[], categoryCount: number): number {
+    if (kind === ChartKind.Stacked) {
+        return Math.max(0, ...Array.from({ length: categoryCount }, (_, index) => series.reduce((sum, item) => sum + Math.max(0, item.values[index] ?? 0), 0)));
+    }
+
+    return Math.max(0, ...series.flatMap(item => item.values));
+}
+
+/** A slice of a donut, in radians clockwise from the top. */
+export interface DonutSlice {
+    index: number;
+    value: number;
+    share: number;
+    start: number;
+    end: number;
+}
+
+/** Divides the positive values into slices that together make one turn. */
+export function donutSlices(values: number[]): DonutSlice[] {
+    const positive = values.map(value => Math.max(0, value));
+    const total = positive.reduce((sum, value) => sum + value, 0);
+    if (total === 0) return [];
+
+    let angle = 0;
+    return positive.flatMap((value, index) => {
+        if (value === 0) return [];
+        const share = value / total;
+        const slice = { index, value, share, start: angle, end: angle + share * Math.PI * 2 };
+        angle = slice.end;
+        return [slice];
+    });
+}
+
+/** The SVG path of a ring segment between two radii; a full turn is drawn as two halves, because one arc cannot start and end on the same point. */
+export function ringPath(centerX: number, centerY: number, outer: number, inner: number, start: number, end: number): string {
+    const point = (radius: number, angle: number) => `${(centerX + radius * Math.sin(angle)).toFixed(2)} ${(centerY - radius * Math.cos(angle)).toFixed(2)}`;
+    if (end - start >= Math.PI * 2 - 1e-6) {
+        const middle = start + Math.PI;
+        return `${ringPath(centerX, centerY, outer, inner, start, middle)} ${ringPath(centerX, centerY, outer, inner, middle, end)}`;
+    }
+
+    const large = end - start > Math.PI ? 1 : 0;
+    return `M ${point(outer, start)} A ${outer} ${outer} 0 ${large} 1 ${point(outer, end)} L ${point(inner, end)} A ${inner} ${inner} 0 ${large} 0 ${point(inner, start)} Z`;
+}
+
+/** One stage of a funnel: a centered bar whose width is its share of the widest stage. */
+export interface FunnelStage {
+    index: number;
+    value: number;
+    widthRatio: number;
+}
+
+/** Sizes the stages of a funnel against the largest value. */
+export function funnelStages(values: number[]): FunnelStage[] {
+    const maximum = Math.max(0, ...values);
+    return values.map((value, index) => ({ index, value, widthRatio: maximum === 0 ? 0 : Math.max(0, value) / maximum }));
+}