@cratis/scene.blueprint.default 4.35.0 → 4.36.0

package/foundation/ActivityFeed.tsx

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { readOptionalString } from '../shell/elementProperties';
+import { ActivityKind, groupByDay, readActivity } from './activityModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon, FoundationIconName } from './FoundationIcon';
+import { formatDate, formatDay, readLocale } from './formatting';
+import { readFoundationStrings } from './foundationStrings';
+import { FoundationFrame } from './StateFrame';
+
+const icons: Record<ActivityKind, FoundationIconName> = {
+    [ActivityKind.Comment]: 'user', [ActivityKind.Change]: 'refresh', [ActivityKind.Status]: 'check', [ActivityKind.System]: 'info',
+};
+
+/**
+ * The `activityFeed` component: what happened to a record, newest first, under a heading for each day.
+ *
+ * `entries` carry an id, who (`actor`), what (`action`), the instant (`at`, ISO 8601), a `kind` and an optional `body` such as a comment's
+ * text. The feed is an ordered list; each entry names its kind in words for assistive technology as well as by icon, and its time is a
+ * `time` element formatted for the locale. Content is supplied by the application - this only lays it out - and a feed of any length
+ * stays one list. `order="ascending"` reads oldest first, and `timeZone` fixes the zone days are cut in.
+ */
+export function ActivityFeed({ element, interactions }: RegisteredComponentProps) {
+    const entries = useMemo(() => readActivity(element.properties.entries), [element.properties.entries]);
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const timeZone = readOptionalString(element, 'timeZone');
+    const days = useMemo(() => groupByDay(entries, element.properties.order === 'ascending', timeZone), [entries, element.properties.order, timeZone]);
+    const state = readComponentState(element, entries.length > 0);
+    const kindText: Record<ActivityKind, string> = { comment: strings.activityComment, change: strings.activityChange, status: strings.activityStatus, system: strings.activitySystem };
+    const emptyElement = state === ComponentState.Empty ? { ...element, properties: { emptyHeadline: strings.activityEmpty, ...element.properties } } : element;
+
+    return (
+        <FoundationFrame element={emptyElement} interactions={interactions} name='activity-feed' state={state} skeleton={[60, 90, 70, 85]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && days.map(day => (
+                <section key={day.day} className='foundation-activity-day'>
+                    <h3 className='foundation-activity-heading'><time dateTime={day.day}>{formatDay(day.day, locale)}</time></h3>
+                    <ol className='foundation-activity-list'>
+                        {day.entries.map(entry => (
+                            <li key={entry.id} className='foundation-activity-entry' data-kind={entry.kind}>
+                                <span className='foundation-activity-icon'><FoundationIcon name={icons[entry.kind]} /></span>
+                                <div className='foundation-activity-content'>
+                                    <p className='foundation-activity-summary'>
+                                        <span className='foundation-visually-hidden'>{`${kindText[entry.kind]}: `}</span>
+                                        <strong>{entry.actor}</strong> {entry.action}
+                                    </p>
+                                    {entry.body && <p className='foundation-activity-body'>{entry.body}</p>}
+                                    <time className='foundation-count' dateTime={entry.at}>{formatDate(entry.at, locale, true)}</time>
+                                </div>
+                            </li>
+                        ))}
+                    </ol>
+                </section>
+            ))}
+        </FoundationFrame>
+    );
+}
+

package/foundation/AvatarStack.tsx

@@ -0,0 +1,43 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { useMemo } from 'react';
+import { RegisteredComponentProps } from '@cratis/scene.react';
+import { initialsOf, readPeople, visiblePeople } from './avatarModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { FoundationFrame } from './StateFrame';
+
+/**
+ * The `avatarStack` component: overlapping avatars for the people on a record, with a "+N" chip for the rest.
+ *
+ * `people` are names with an optional picture; without one the avatar shows the person's initials. The stack is a labelled group ("5 people"),
+ * each avatar is an image named after its person, and the overflow chip says how many more in words. `max` is how many are shown (4 by
+ * default) and `size` is `small` or `medium`.
+ */
+export function AvatarStack({ element, interactions }: RegisteredComponentProps) {
+    const people = useMemo(() => readPeople(element.properties.people), [element.properties.people]);
+    const strings = readFoundationStrings(element);
+    const { shown, hidden } = visiblePeople(people, typeof element.properties.max === 'number' ? element.properties.max : 4);
+    const state = readComponentState(element, people.length > 0);
+    const size = element.properties.size === 'small' ? 'small' : 'medium';
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='avatar-stack' state={state} skeleton={[35]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && (
+                <ul className='foundation-avatars' role='group' aria-label={formatText(strings.avatarPeople, { count: people.length })} data-size={size}>
+                    {shown.map(person => (
+                        <li key={person.name} className='foundation-avatar' role='img' aria-label={person.name} title={person.name}>
+                            {person.imageUrl ? <img src={person.imageUrl} alt='' /> : <span aria-hidden='true'>{initialsOf(person.name)}</span>}
+                        </li>
+                    ))}
+                    {hidden > 0 && (
+                        <li className='foundation-avatar foundation-avatar-more' role='img' aria-label={formatText(strings.avatarOverflow, { count: hidden })}>
+                            <span aria-hidden='true'>+{hidden}</span>
+                        </li>
+                    )}
+                </ul>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/ChecklistSection.tsx

@@ -0,0 +1,80 @@
+// 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 { ChecklistGroup, completed, doneTaskIds, isOverdue, readChecklist, toggleTask } from './checklistModel';
+import { ComponentState, readComponentState } from './ComponentState';
+import { FoundationIcon } from './FoundationIcon';
+import { formatDate, readLocale } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+import { FoundationFrame } from './StateFrame';
+
+/**
+ * The `checklistSection` component: sections of tasks, each with its owner and due date, and a progress bar per section.
+ *
+ * `sections` give the structure (`title`, and `items` with `id`, `label`, `owner`, `due`, `done`). Ticking a task publishes the ids of all
+ * done tasks as the `value` output and runs the behaviors attached to the element. An open task past its due date says "Overdue" in
+ * words as well as in color. Progress is a labelled progress bar, so "2 of 5 complete" is read, not just seen. With `editPermission`
+ * not enabled the tasks are shown and cannot be changed.
+ */
+export function ChecklistSection({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const supplied = useMemo(() => readChecklist(element.properties.sections), [element.properties.sections]);
+    const suppliedKey = JSON.stringify(supplied);
+    const [groups, setGroups] = useState<ChecklistGroup[]>(supplied);
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const state = readComponentState(element, supplied.some(group => group.items.length > 0));
+    const locked = readPermissionRule(element, 'editPermission') !== 'enabled';
+    const now = useMemo(() => (typeof element.properties.today === 'string' ? new Date(element.properties.today) : new Date()), [element.properties.today]);
+
+    useEffect(() => setGroups(supplied), [suppliedKey]);
+    useValueOutput(bindingOutputs, doneTaskIds(groups));
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='checklist' state={state} skeleton={[40, 100, 90, 95]}>
+            {(state === ComponentState.Ready || state === ComponentState.Partial) && groups.map((group, groupIndex) => {
+                const done = completed(group);
+                const total = group.items.length;
+                return (
+                    <section key={group.title + groupIndex} className='foundation-checklist-group' aria-labelledby={`${element.id}-group-${groupIndex}`}>
+                        <header className='foundation-checklist-header'>
+                            <h3 id={`${element.id}-group-${groupIndex}`}>{group.title}</h3>
+                            <span className='foundation-count'>{formatText(strings.checklistProgress, { done, total })}</span>
+                        </header>
+                        <div className='foundation-progress' role='progressbar' aria-label={formatText(strings.checklistItemProgress, { title: group.title })}
+                            aria-valuemin={0} aria-valuemax={total} aria-valuenow={done} aria-valuetext={formatText(strings.checklistProgress, { done, total })}>
+                            <span className='foundation-progress-bar' style={{ inlineSize: total === 0 ? '0%' : `${(done / total) * 100}%` }} />
+                        </div>
+                        {total === 0 ? <p className='foundation-count'>{strings.checklistNone}</p> : (
+                            <ul className='foundation-checklist-items'>
+                                {group.items.map(item => {
+                                    const overdue = isOverdue(item, now);
+                                    return (
+                                        <li key={item.id} className='foundation-checklist-item' data-done={item.done} data-overdue={overdue}>
+                                            <label className='foundation-check'>
+                                                <input type='checkbox' checked={item.done} disabled={locked} onChange={() => { setGroups(toggleTask(groups, item.id)); interactions?.onChange?.(); }} />
+                                                <span className='foundation-checklist-label'>{item.label}</span>
+                                            </label>
+                                            <span className='foundation-checklist-meta'>
+                                                {item.owner && <span><span className='foundation-visually-hidden'>{`${strings.checklistOwner}: `}</span><FoundationIcon name='user' /> {item.owner}</span>}
+                                                {item.due && (
+                                                    <span>
+                                                        <span className='foundation-visually-hidden'>{`${strings.checklistDue}: `}</span>
+                                                        <time dateTime={item.due}>{formatDate(item.due, locale)}</time>
+                                                        {overdue && <strong className='foundation-overdue'> · <FoundationIcon name='alert' /> {strings.checklistOverdue}</strong>}
+                                                    </span>
+                                                )}
+                                            </span>
+                                        </li>
+                                    );
+                                })}
+                            </ul>
+                        )}
+                    </section>
+                );
+            })}
+        </FoundationFrame>
+    );
+}

package/foundation/FileUploader.tsx

@@ -0,0 +1,122 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ChangeEvent, DragEvent, useRef, useState } from 'react';
+import { RegisteredComponentProps, useValueOutput } from '@cratis/scene.react';
+import { readOptionalString } from '../shell/elementProperties';
+import { ActionButton } from './ActionButton';
+import { ComponentState, readComponentState } from './ComponentState';
+import { useFileUploaderHandler } from './FileUploaderHandler';
+import { FoundationIcon } from './FoundationIcon';
+import { readLocale } from './formatting';
+import { formatText, readFoundationStrings } from './foundationStrings';
+import { readPermissionRule } from './PermissionRule';
+import { FoundationFrame } from './StateFrame';
+import { UploadRefusal, UploadStatus, checkSelection, formatBytes } from './uploadModel';
+
+interface Entry {
+    file: File;
+    status: UploadStatus;
+}
+
+/**
+ * The `fileUploader` component: a drop zone and a button to choose files, checked against type and size before anything is sent.
+ *
+ * `accept` is an `accept` list, `maxSizeMb` the largest file, and `multiple` whether more than one is allowed. The zone is a real file
+ * input behind a labelled button, so it works from the keyboard and with a screen reader; dropping onto it does the same as choosing.
+ * Refusals are announced with their reason. Accepted files are listed with a remove button and a status in words; the selection
+ * (name, size, type) is published as the `value` output. With a `FileUploaderHandlerProvider` in scope the files are sent through it and
+ * marked uploading, done or failed; without one the component only collects. `actionPermission` gates choosing files.
+ */
+export function FileUploader({ element, interactions, bindingOutputs }: RegisteredComponentProps) {
+    const strings = readFoundationStrings(element);
+    const locale = readLocale(element);
+    const handler = useFileUploaderHandler();
+    const [entries, setEntries] = useState<Entry[]>([]);
+    const [problems, setProblems] = useState<string[]>([]);
+    const [dragging, setDragging] = useState(false);
+    const input = useRef<HTMLInputElement>(null);
+    const accept = readOptionalString(element, 'accept') ?? '';
+    const maximumBytes = (typeof element.properties.maxSizeMb === 'number' ? element.properties.maxSizeMb : 0) * 1024 * 1024;
+    const multiple = element.properties.multiple !== false;
+    const rule = readPermissionRule(element, 'actionPermission');
+    const state = readComponentState(element, true);
+    const serverUrl = readOptionalString(element, 'serverUrl');
+
+    useValueOutput(bindingOutputs, entries.map(entry => ({ name: entry.file.name, size: entry.file.size, type: entry.file.type, status: entry.status })));
+
+    const send = async (files: File[]) => {
+        if (!handler) return;
+        const mark = (status: UploadStatus) => setEntries(current => current.map(entry => (files.includes(entry.file) ? { ...entry, status } : entry)));
+        mark(UploadStatus.Uploading);
+        try {
+            await handler(files, serverUrl);
+            mark(UploadStatus.Done);
+        } catch {
+            mark(UploadStatus.Failed);
+        }
+    };
+
+    const take = (chosen: File[]) => {
+        const { accepted, refused } = checkSelection(chosen, { accept, maximumBytes, multiple }, entries.length);
+        setProblems(refused.map(({ file, reason }) => reason === UploadRefusal.WrongType ? formatText(strings.uploadWrongType, { name: file.name })
+            : reason === UploadRefusal.TooLarge ? formatText(strings.uploadTooLarge, { name: file.name, limit: formatBytes(maximumBytes, locale) }) : strings.uploadSingle));
+        if (accepted.length === 0) return;
+
+        setEntries(current => [...current, ...accepted.map(file => ({ file, status: UploadStatus.Queued }))]);
+        interactions?.onChange?.();
+        void send(accepted);
+    };
+
+    const choose = (event: ChangeEvent<HTMLInputElement>) => {
+        take(Array.from(event.target.files ?? []));
+        event.target.value = '';
+    };
+    const drop = (event: DragEvent) => {
+        event.preventDefault();
+        setDragging(false);
+        if (rule === 'enabled') take(Array.from(event.dataTransfer.files));
+    };
+    const statusText: Record<UploadStatus, string> = {
+        queued: strings.uploadQueued, uploading: strings.uploadUploading, done: strings.uploadDone, failed: strings.uploadFailed,
+    };
+    const limits = [accept ? formatText(strings.uploadAccepts, { types: accept }) : '', maximumBytes > 0 ? formatText(strings.uploadLimits, { limit: formatBytes(maximumBytes, locale) }) : ''].filter(Boolean).join(' · ');
+
+    return (
+        <FoundationFrame element={element} interactions={interactions} name='file-uploader' state={state} skeleton={[100, 40]}>
+            {state !== ComponentState.Loading && (
+                <>
+                    <div className='foundation-dropzone' data-dragging={dragging} onDragOver={event => { event.preventDefault(); setDragging(true); }} onDragLeave={() => setDragging(false)} onDrop={drop}>
+                        <FoundationIcon name='upload' />
+                        <span>{strings.uploadDrop}</span>
+                        <input ref={input} className='foundation-visually-hidden' type='file' tabIndex={-1} accept={accept || undefined} multiple={multiple} disabled={rule !== 'enabled'} onChange={choose} aria-hidden='true' />
+                        <ActionButton rule={rule} emphasis='secondary' disabledReason={strings.disabledNoPermission} onClick={() => input.current?.click()}>
+                            {strings.uploadBrowse}
+                        </ActionButton>
+                        {limits && <span className='foundation-count'>{limits}</span>}
+                    </div>
+                    <div aria-live='polite' className='foundation-upload-problems'>
+                        {problems.map(problem => <p key={problem} className='foundation-message-text' data-tone='danger'>{problem}</p>)}
+                    </div>
+                    {entries.length > 0 && (
+                        <ul className='foundation-upload-list' aria-label={strings.uploadSelected}>
+                            {entries.map((entry, index) => (
+                                <li key={entry.file.name + index} className='foundation-upload-item' data-status={entry.status}>
+                                    <FoundationIcon name='file' />
+                                    <span className='foundation-upload-name'>{entry.file.name}</span>
+                                    <span className='foundation-count'>{formatBytes(entry.file.size, locale)}</span>
+                                    <span className='foundation-upload-status'>{statusText[entry.status]}</span>
+                                    {entry.status === UploadStatus.Failed && <button type='button' className='foundation-link' onClick={() => void send([entry.file])}>{strings.retry}</button>}
+                                    <button type='button' className='foundation-icon-button' aria-label={formatText(strings.uploadRemove, { name: entry.file.name })}
+                                        onClick={() => { setEntries(current => current.filter(existing => existing !== entry)); interactions?.onChange?.(); }}>
+                                        <FoundationIcon name='close' />
+                                    </button>
+                                </li>
+                            ))}
+                        </ul>
+                    )}
+                </>
+            )}
+        </FoundationFrame>
+    );
+}

package/foundation/FileUploaderHandler.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 { ReactNode, createContext, useContext } from 'react';
+
+/**
+ * What sends the accepted files somewhere: a host's server client, kept out of the portable package.
+ *
+ * The signature is the one `@cratis/scene.primereact` uses for its `fileUpload`, so a host hands the same function to both. A handler that
+ * rejects marks the files as failed, with a retry; without a handler the uploader only collects and publishes the selection.
+ */
+export type FileUploaderHandler = (files: File[], serverUrl?: string) => Promise<void>;
+
+const Context = createContext<FileUploaderHandler | undefined>(undefined);
+
+/** Provides the upload handler to the file uploaders below it. */
+export function FileUploaderHandlerProvider({ handler, children }: { handler?: FileUploaderHandler; children: ReactNode }) {
+    return <Context.Provider value={handler}>{children}</Context.Provider>;
+}
+
+/** The handler in scope, if any. */
+export const useFileUploaderHandler = (): FileUploaderHandler | undefined => useContext(Context);

package/foundation/Foundation.stories.tsx

@@ -44,3 +44,11 @@ export const ColumnChooserLight: Story = { args: { component: ComponentName.Colu
 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' } };
+export const ChecklistLight: Story = { args: { component: ComponentName.ChecklistSection, theme: 'light' } };
+export const ChecklistDark: Story = { args: { component: ComponentName.ChecklistSection, theme: 'dark' } };
+export const ActivityFeedLight: Story = { args: { component: ComponentName.ActivityFeed, theme: 'light' } };
+export const ActivityFeedDark: Story = { args: { component: ComponentName.ActivityFeed, theme: 'dark' } };
+export const AvatarStackLight: Story = { args: { component: ComponentName.AvatarStack, theme: 'light' } };
+export const AvatarStackDark: Story = { args: { component: ComponentName.AvatarStack, theme: 'dark' } };
+export const FileUploaderLight: Story = { args: { component: ComponentName.FileUploader, theme: 'light' } };
+export const FileUploaderDark: Story = { args: { component: ComponentName.FileUploader, theme: 'dark' } };

package/foundation/activityModel.ts

@@ -0,0 +1,65 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** What kind of thing happened, which decides the icon and the word that tells it apart without color. */
+export enum ActivityKind {
+    Comment = 'comment',
+    Change = 'change',
+    Status = 'status',
+    System = 'system',
+}
+
+/** One thing that happened to a record. */
+export interface ActivityEntry {
+    id: string;
+    actor: string;
+    action: string;
+    kind: ActivityKind;
+    at: string;
+    body?: string;
+}
+
+/** The entries of one day, in the order the feed shows them. */
+export interface ActivityDay {
+    day: string;
+    entries: ActivityEntry[];
+}
+
+/** Reads entries out of a property value, dropping those without an id or a time that parses. */
+export function readActivity(value: unknown): ActivityEntry[] {
+    if (!Array.isArray(value)) return [];
+
+    return value.flatMap((entry): ActivityEntry[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { id, actor, action, kind, at, body } = entry as Record<string, unknown>;
+        if (typeof id !== 'string' || typeof at !== 'string' || Number.isNaN(new Date(at).getTime())) return [];
+
+        return [{
+            id, at,
+            actor: typeof actor === 'string' ? actor : '',
+            action: typeof action === 'string' ? action : '',
+            kind: (Object.values(ActivityKind) as string[]).includes(kind as string) ? (kind as ActivityKind) : ActivityKind.System,
+            ...(typeof body === 'string' && body.length > 0 ? { body } : {}),
+        }];
+    });
+}
+
+/** The calendar day of an instant in a time zone, as `YYYY-MM-DD`. */
+export function dayOf(at: string, timeZone?: string): string {
+    return new Intl.DateTimeFormat('en-CA', { timeZone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(new Date(at));
+}
+
+/** Sorts the entries by time (newest first unless `ascending`) and groups them by calendar day, so a long feed has headings to scan by. */
+export function groupByDay(entries: ActivityEntry[], ascending = false, timeZone?: string): ActivityDay[] {
+    const sorted = [...entries].sort((first, second) => (new Date(first.at).getTime() - new Date(second.at).getTime()) * (ascending ? 1 : -1));
+    const days: ActivityDay[] = [];
+
+    for (const entry of sorted) {
+        const day = dayOf(entry.at, timeZone);
+        const last = days[days.length - 1];
+        if (last?.day === day) last.entries.push(entry);
+        else days.push({ day, entries: [entry] });
+    }
+
+    return days;
+}

package/foundation/avatarModel.ts

@@ -0,0 +1,36 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** A person shown as an avatar. */
+export interface AvatarPerson {
+    name: string;
+    imageUrl?: string;
+}
+
+/** Reads people out of a property value, dropping entries without a name. */
+export function readPeople(value: unknown): AvatarPerson[] {
+    if (!Array.isArray(value)) return [];
+
+    return value.flatMap((entry): AvatarPerson[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { name, imageUrl } = entry as Record<string, unknown>;
+        if (typeof name !== 'string' || name.trim().length === 0) return [];
+        return [{ name: name.trim(), ...(typeof imageUrl === 'string' && imageUrl.length > 0 ? { imageUrl } : {}) }];
+    });
+}
+
+/** The initials of a name: the first letter of the first and last words, so "Ada King Lovelace" is AL and "Ada" is A. */
+export function initialsOf(name: string): string {
+    const words = name.split(/\s+/).filter(word => word.length > 0);
+    if (words.length === 0) return '';
+
+    const first = Array.from(words[0])[0] ?? '';
+    const last = words.length > 1 ? Array.from(words[words.length - 1])[0] ?? '' : '';
+    return `${first}${last}`.toLocaleUpperCase();
+}
+
+/** Splits people into those shown and how many are folded into the "+N" chip; at least one is always shown when there are any. */
+export function visiblePeople(people: AvatarPerson[], maximum: number): { shown: AvatarPerson[]; hidden: number } {
+    const limit = Math.max(1, Math.floor(maximum));
+    return people.length <= limit ? { shown: people, hidden: 0 } : { shown: people.slice(0, limit), hidden: people.length - limit };
+}

package/foundation/checklistModel.ts

@@ -0,0 +1,62 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** One task of a checklist. */
+export interface ChecklistItem {
+    id: string;
+    label: string;
+    owner?: string;
+    due?: string;
+    done: boolean;
+}
+
+/** A titled group of tasks. */
+export interface ChecklistGroup {
+    title: string;
+    items: ChecklistItem[];
+}
+
+/** Reads checklist groups out of a property value; a task needs an id and a label, and is open unless it says it is done. */
+export function readChecklist(value: unknown): ChecklistGroup[] {
+    if (!Array.isArray(value)) return [];
+
+    return value.flatMap((entry): ChecklistGroup[] => {
+        if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) return [];
+        const { title, items } = entry as Record<string, unknown>;
+        if (typeof title !== 'string' || !Array.isArray(items)) return [];
+
+        return [{
+            title,
+            items: items.flatMap((item): ChecklistItem[] => {
+                if (typeof item !== 'object' || item === null || Array.isArray(item)) return [];
+                const { id, label, owner, due, done } = item as Record<string, unknown>;
+                if (typeof id !== 'string' || typeof label !== 'string') return [];
+                return [{ id, label, done: done === true, ...(typeof owner === 'string' ? { owner } : {}), ...(typeof due === 'string' ? { due } : {}) }];
+            }),
+        }];
+    });
+}
+
+/** How many of a group's tasks are done. */
+export const completed = (group: ChecklistGroup): number => group.items.filter(item => item.done).length;
+
+/** Whether an open task is past its due date, today counting as not yet late. */
+export function isOverdue(item: ChecklistItem, now: Date): boolean {
+    if (item.done || item.due === undefined) return false;
+
+    const due = new Date(item.due);
+    if (Number.isNaN(due.getTime())) return false;
+
+    const endOfDue = new Date(due);
+    endOfDue.setUTCHours(23, 59, 59, 999);
+    return endOfDue.getTime() < now.getTime();
+}
+
+/** Marks one task done or open, leaving every other as it was. */
+export const toggleTask = (groups: ChecklistGroup[], id: string): ChecklistGroup[] =>
+    groups.map(group => (group.items.some(item => item.id === id)
+        ? { ...group, items: group.items.map(item => (item.id === id ? { ...item, done: !item.done } : item)) }
+        : group));
+
+/** The ids of every done task: what the checklist publishes. */
+export const doneTaskIds = (groups: ChecklistGroup[]): string[] => groups.flatMap(group => group.items.filter(item => item.done).map(item => item.id));

package/foundation/formatting.ts

@@ -67,3 +67,12 @@ export function formatDate(value: unknown, locale: string, withTime = false): st
         return date.toISOString();
     }
 }
+
+/** Formats a calendar day (`YYYY-MM-DD`) for a locale, as that day and never shifted by the reader's time zone. */
+export function formatDay(day: string, locale: string): string {
+    try {
+        return new Intl.DateTimeFormat(locale, { dateStyle: 'full', timeZone: 'UTC' }).format(new Date(`${day}T12:00:00Z`));
+    } catch {
+        return day;
+    }
+}

package/foundation/foundationComponentMetadata.ts

@@ -18,4 +18,8 @@ export const foundationComponentMetadata: Record<string, ComponentMetadata> = {
     [ComponentName.FilterBuilder]: m('Filter builder', ComponentCategory.Input, 'list-filter', ['filter', 'query', 'conditions', 'and or', 'search']),
     [ComponentName.ColumnChooser]: m('Column chooser', ComponentCategory.Actions, 'columns-3', ['columns', 'fields', 'show hide', 'table']),
     [ComponentName.SavedViewsMenu]: m('Saved views menu', ComponentCategory.Actions, 'bookmark', ['views', 'presets', 'saved filters']),
+    [ComponentName.ChecklistSection]: m('Checklist', ComponentCategory.DataDisplay, 'list-checks', ['tasks', 'todo', 'onboarding', 'progress', 'steps']),
+    [ComponentName.ActivityFeed]: m('Activity feed', ComponentCategory.DataDisplay, 'activity', ['timeline', 'history', 'comments', 'audit', 'log']),
+    [ComponentName.AvatarStack]: m('Avatar stack', ComponentCategory.DataDisplay, 'users', ['people', 'members', 'assignees', 'team']),
+    [ComponentName.FileUploader]: m('File uploader', ComponentCategory.Input, 'upload', ['attachments', 'files', 'drop zone', 'documents']),
 };

package/foundation/foundationDescriptors.ts

@@ -5,6 +5,7 @@ import { BindingSourceKind, ComponentDescriptor, PropertyDescriptor, PropertyEdi
 import { componentRegistryKey, valueOutputProperty } from '@cratis/scene.react';
 import { ComponentName } from '../ComponentName';
 import { defaultBlueprintName } from '../packageName';
+import { ActivityKind } from './activityModel';
 import { ChartKind } from './chartGeometry';
 import { ComponentState } from './ComponentState';
 import { FilterFieldType } from './filterModel';
@@ -200,5 +201,83 @@ export const foundationDescriptors: ComponentDescriptor[] = [
             ...standardStateProperties,
         ],
     },
+    {
+        component: key(ComponentName.ChecklistSection),
+        displayName: 'Checklist',
+        description: 'Sections of tasks with an owner and due date each and a progress bar per section. Publishes the ids of the done tasks as the value output.',
+        properties: [
+            {
+                ...list('sections', 'Sections', 'Data', 'Section', [
+                    text('title', 'Title', 'Content', undefined, { constraints: { required: true } }),
+                    list('items', 'Tasks', 'Data', 'Task', [
+                        text('id', 'Id', 'Data', undefined, { constraints: { required: true } }),
+                        text('label', 'Task', 'Content', undefined, { constraints: { required: true } }),
+                        text('owner', 'Owner', 'Data'),
+                        text('due', 'Due date', 'Data', 'An ISO 8601 date.'),
+                        flag('done', 'Done', 'Data'),
+                    ]),
+                ], 'The groups of tasks.'),
+                acceptedBindingKinds: bindable,
+            },
+            text('today', 'Today', 'Content', 'The date overdue is judged against; empty is the current date.'),
+            rule('editPermission', 'Edit permission', 'Enabled lets the user tick tasks; otherwise they are shown read-only.'),
+            valueOutputProperty(PropertyValueType.Json, 'The ids of the done tasks, published as the user ticks them.'),
+            ...standardStateProperties,
+        ],
+    },
+    {
+        component: key(ComponentName.ActivityFeed),
+        displayName: 'Activity feed',
+        description: 'What happened to a record, grouped by day. Content is supplied by the application; this lays it out.',
+        properties: [
+            {
+                ...list('entries', 'Entries', 'Data', 'Entry', [
+                    text('id', 'Id', 'Data', undefined, { constraints: { required: true } }),
+                    text('actor', 'Who', 'Data'),
+                    text('action', 'What', 'Data'),
+                    choice('kind', 'Kind', 'Data', {
+                        [ActivityKind.Comment]: 'Comment', [ActivityKind.Change]: 'Change', [ActivityKind.Status]: 'Status', [ActivityKind.System]: 'System',
+                    }, ActivityKind.System),
+                    text('at', 'When', 'Data', 'An ISO 8601 date and time.', { constraints: { required: true } }),
+                    text('body', 'Text', 'Data', 'A comment\'s text or the detail of a change.', { editorOptions: { multiline: true } }),
+                ], 'What happened.'),
+                acceptedBindingKinds: bindable,
+            },
+            choice('order', 'Order', 'Appearance', { descending: 'Newest first', ascending: 'Oldest first' }, 'descending'),
+            text('timeZone', 'Time zone', 'Content', 'The IANA zone days are cut in; empty is the reader\'s.'),
+            ...standardStateProperties,
+        ],
+    },
+    {
+        component: key(ComponentName.AvatarStack),
+        displayName: 'Avatar stack',
+        description: 'Overlapping avatars for the people on a record, with a "+N" chip for the rest.',
+        properties: [
+            {
+                ...list('people', 'People', 'Data', 'Person', [
+                    text('name', 'Name', 'Data', undefined, { constraints: { required: true } }),
+                    text('imageUrl', 'Picture', 'Data', 'Without one the initials are shown.'),
+                ], 'Who is shown.'),
+                acceptedBindingKinds: bindable,
+            },
+            number('max', 'Shown at most', 'Appearance', 'How many avatars before the rest fold into "+N".', { default: 4, constraints: { minimum: 1, integer: true } }),
+            choice('size', 'Size', 'Appearance', { small: 'Small', medium: 'Medium' }, 'medium'),
+            ...standardStateProperties,
+        ],
+    },
+    {
+        component: key(ComponentName.FileUploader),
+        displayName: 'File uploader',
+        description: 'A drop zone and a button to choose files, checked against type and size before anything is sent. Publishes the selection as the value output.',
+        properties: [
+            text('accept', 'Accepted types', 'Behavior', 'Extensions, MIME types and wildcards separated by commas, for example ".pdf, image/*".'),
+            number('maxSizeMb', 'Largest file (MB)', 'Behavior', undefined, { constraints: { minimum: 0 } }),
+            flag('multiple', 'Several files', 'Behavior', undefined, { default: true }),
+            text('serverUrl', 'Upload address', 'Behavior', 'Handed to the host\'s upload handler.'),
+            rule('actionPermission', 'Upload permission', 'Whether files can be chosen or dropped, refused with a reason, or the control is hidden.'),
+            valueOutputProperty(PropertyValueType.Json, 'The files chosen - name, size, type and status - published as they change.'),
+            ...standardStateProperties.filter(property => property.path !== 'actionPermission'),
+        ],
+    },
 ];