@tristan2828/ui-foundation 4.50.1 → 4.52.0

package/conventions/docs/design-language.md

@@ -3,24 +3,25 @@
 <!-- index: written by `npm run docs:index` in the package from the headings below; never edit it by hand -->
 ## Index
 
-- [Semantic tones](#semantic-tones) · lines 33–61
-- [The three badge styles](#the-three-badge-styles) · lines 63–80
-- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 82–111
-- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 113–126
-- [Logos and brand marks](#logos-and-brand-marks) · lines 128–172
-- [Categorical colour](#categorical-colour) · lines 174–244
-- [Typography](#typography) · lines 246–337
-  - [Written text (notes)](#written-text-notes) · lines 277–337
-- [Density](#density) · lines 339–396
-- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 398–512
-- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 514–583
-- [Notices](#notices) · lines 585–613
-- [A value over time](#a-value-over-time) · lines 615–648
-- [A list as a board](#a-list-as-a-board) · lines 650–701
-- [A list as cards](#a-list-as-cards) · lines 703–749
-- [Key numbers on a record](#key-numbers-on-a-record) · lines 751–773
-- [Picking at random](#picking-at-random) · lines 775–806
-- [Filling in what's missing](#filling-in-whats-missing) · lines 808–858
+- [Semantic tones](#semantic-tones) · lines 34–62
+- [The three badge styles](#the-three-badge-styles) · lines 64–81
+- [Mapping an enum to tones](#mapping-an-enum-to-tones) · lines 83–112
+- [Glyphs and icons: 3:1](#glyphs-and-icons-31) · lines 114–127
+- [Logos and brand marks](#logos-and-brand-marks) · lines 129–173
+- [Categorical colour](#categorical-colour) · lines 175–245
+- [Typography](#typography) · lines 247–338
+  - [Written text (notes)](#written-text-notes) · lines 278–338
+- [Density](#density) · lines 340–397
+- [Widget cards (hub pages)](#widget-cards-hub-pages) · lines 399–513
+- [Module cards (a hub's places)](#module-cards-a-hubs-places) · lines 515–584
+- [Notices](#notices) · lines 586–614
+- [A value over time](#a-value-over-time) · lines 616–694
+  - [Several values over time](#several-values-over-time) · lines 657–694
+- [A list as a board](#a-list-as-a-board) · lines 696–747
+- [A list as cards](#a-list-as-cards) · lines 749–795
+- [Key numbers on a record](#key-numbers-on-a-record) · lines 797–819
+- [Picking at random](#picking-at-random) · lines 821–852
+- [Filling in what's missing](#filling-in-whats-missing) · lines 854–904
 
 <!-- /index -->
 
@@ -644,8 +645,53 @@ or `'last'`) with its value.
   named by `label`, with a summary (first, last, lowest, highest, the
   target) and a table of every point. Give it the same `formatY` and
   `formatX` the page uses for those values elsewhere.
-- One series and a few dozen points. Several series, zoom or tooltips
-  are a request for the foundation, not a hand-drawn chart in the app.
+- **A projection** (4.51): `projection={{ label: 'Projected', points }}`
+  carries the line on past its last point, dashed in the same colour, for
+  where a value may go (a balance at a rate of return), never for what was
+  measured. Its points come after the last of `points`; the mark stays on
+  `points`, and a screen reader gets the projection's end in the summary
+  and its rows in the table, each named by `label`.
+- One series and a few dozen points. Zoom or tooltips are a request for
+  the foundation, not a hand-drawn chart in the app.
+
+### Several values over time
+
+`MultiLineChart` (4.51) puts several series on one plot, sharing one x
+and one y range: a net worth beside its assets and what's owed, or a
+balance's history beside low, middle and high projections.
+
+```tsx
+<MultiLineChart
+  label="Net worth over time"
+  series={[
+    { label: 'Assets', tone: 'success', points: assets },
+    { label: 'Owed', tone: 'destructive', points: owed },
+    { label: 'Net worth', points: netWorth },
+  ]}
+  target={{ y: 1_500_000, label: 'Target' }}
+  formatY={usd}
+  formatX={month}
+  isLoading={isLoading}
+/>
+```
+
+- **Tones, not colours:** each series takes a text tone (`info`, the
+  default, `success`, `warning`, `destructive` or `muted`), each clearing
+  3:1 on a card in both themes. Pick by meaning where there is one (what's
+  owed in `destructive`); otherwise keep the series that matters most in
+  `info` and the rest `muted`.
+- **`dashed` is for what wasn't measured:** a projection or a plan. A
+  projection that starts at the last measured point should repeat that
+  point as its first, so the lines meet.
+- **A legend under the plot** names each series with its latest value,
+  so colour never carries the meaning alone. The target is a dashed
+  `success-text` line, as on `LineChart`.
+- **It owns its states** as `LineChart` does: a skeleton, one quiet line
+  when no series has a point, a dot for a series of one point.
+- **A screen reader gets a summary** (each series from first to last
+  value, and the target) and a table with a column per series.
+- Up to four or five series. More than that, or bars and stacked areas,
+  are a request for the foundation.
 
 ## A list as a board
 

package/dist/components/app/emoji-field-data.d.ts

@@ -0,0 +1,11 @@
+export type EmojiEntry = {
+    emoji: string;
+    name: string;
+    keywords?: string;
+};
+export type EmojiGroup = {
+    label: string;
+    emojis: EmojiEntry[];
+};
+export declare const EMOJI_GROUPS: EmojiGroup[];
+export declare function filterEmojiGroups(query: string): EmojiGroup[];

package/dist/components/app/emoji-field-data.js

@@ -0,0 +1,157 @@
+export const EMOJI_GROUPS = [
+    {
+        label: 'Morning and sleep',
+        emojis: [
+            { emoji: '☀️', name: 'Sun', keywords: 'morning day bright' },
+            { emoji: '🌅', name: 'Sunrise', keywords: 'morning dawn' },
+            { emoji: '⏰', name: 'Alarm clock', keywords: 'wake time' },
+            { emoji: '🌙', name: 'Moon', keywords: 'night evening' },
+            { emoji: '😴', name: 'Sleeping face', keywords: 'sleep bed rest' },
+            { emoji: '🛏️', name: 'Bed', keywords: 'sleep bedroom' },
+            { emoji: '🌄', name: 'Sunrise over mountains', keywords: 'morning' },
+            { emoji: '🌃', name: 'Night with stars', keywords: 'evening' },
+        ],
+    },
+    {
+        label: 'Body and health',
+        emojis: [
+            { emoji: '🧘', name: 'Person in lotus position', keywords: 'yoga meditate breathe calm' },
+            { emoji: '🏃', name: 'Person running', keywords: 'run exercise workout cardio' },
+            { emoji: '🏋️', name: 'Person lifting weights', keywords: 'gym strength workout' },
+            { emoji: '🚴', name: 'Person biking', keywords: 'cycling exercise' },
+            { emoji: '🏊', name: 'Person swimming', keywords: 'pool exercise' },
+            { emoji: '🤸', name: 'Person cartwheeling', keywords: 'stretch gymnastics' },
+            { emoji: '💪', name: 'Flexed biceps', keywords: 'strength muscle' },
+            { emoji: '🦷', name: 'Tooth', keywords: 'dentist brush teeth' },
+            { emoji: '🪥', name: 'Toothbrush', keywords: 'brush teeth' },
+            { emoji: '💊', name: 'Pill', keywords: 'medicine vitamins' },
+            { emoji: '🩺', name: 'Stethoscope', keywords: 'doctor health' },
+            { emoji: '❤️', name: 'Red heart', keywords: 'love health' },
+            { emoji: '🫁', name: 'Lungs', keywords: 'breathe breath' },
+            { emoji: '🧠', name: 'Brain', keywords: 'mind think' },
+        ],
+    },
+    {
+        label: 'Self-care',
+        emojis: [
+            { emoji: '🚿', name: 'Shower', keywords: 'wash clean' },
+            { emoji: '🛁', name: 'Bathtub', keywords: 'bath wash' },
+            { emoji: '🧼', name: 'Soap', keywords: 'wash clean hands' },
+            { emoji: '🧴', name: 'Lotion bottle', keywords: 'skincare moisturizer sunscreen' },
+            { emoji: '🪒', name: 'Razor', keywords: 'shave' },
+            { emoji: '💇', name: 'Person getting haircut', keywords: 'hair' },
+            { emoji: '🧖', name: 'Person in steamy room', keywords: 'sauna spa relax' },
+            { emoji: '🕯️', name: 'Candle', keywords: 'calm relax' },
+        ],
+    },
+    {
+        label: 'Food and drink',
+        emojis: [
+            { emoji: '🍳', name: 'Cooking', keywords: 'breakfast egg pan' },
+            { emoji: '🥣', name: 'Bowl with spoon', keywords: 'cereal oatmeal breakfast' },
+            { emoji: '🥗', name: 'Green salad', keywords: 'lunch healthy' },
+            { emoji: '🍽️', name: 'Plate with cutlery', keywords: 'meal dinner eat' },
+            { emoji: '🍎', name: 'Red apple', keywords: 'fruit snack' },
+            { emoji: '🥑', name: 'Avocado', keywords: 'food' },
+            { emoji: '☕', name: 'Hot beverage', keywords: 'coffee tea' },
+            { emoji: '🍵', name: 'Teacup', keywords: 'tea' },
+            { emoji: '💧', name: 'Droplet', keywords: 'water drink hydrate' },
+            { emoji: '🥤', name: 'Cup with straw', keywords: 'drink' },
+            { emoji: '🛒', name: 'Shopping cart', keywords: 'groceries store' },
+        ],
+    },
+    {
+        label: 'Home and chores',
+        emojis: [
+            { emoji: '🏠', name: 'House', keywords: 'home' },
+            { emoji: '🧹', name: 'Broom', keywords: 'sweep clean chores' },
+            { emoji: '🧽', name: 'Sponge', keywords: 'scrub clean dishes' },
+            { emoji: '🧺', name: 'Basket', keywords: 'laundry' },
+            { emoji: '👕', name: 'T-shirt', keywords: 'laundry clothes' },
+            { emoji: '🗑️', name: 'Wastebasket', keywords: 'trash garbage' },
+            { emoji: '🛠️', name: 'Hammer and wrench', keywords: 'repair fix tools' },
+            { emoji: '🔧', name: 'Wrench', keywords: 'repair fix' },
+            { emoji: '🔑', name: 'Key', keywords: 'lock keys' },
+            { emoji: '🪴', name: 'Potted plant', keywords: 'garden water plants' },
+            { emoji: '🌱', name: 'Seedling', keywords: 'garden grow plant' },
+            { emoji: '🌿', name: 'Herb', keywords: 'garden plant' },
+            { emoji: '🐕', name: 'Dog', keywords: 'pet walk' },
+            { emoji: '🐈', name: 'Cat', keywords: 'pet' },
+        ],
+    },
+    {
+        label: 'Work and learning',
+        emojis: [
+            { emoji: '💻', name: 'Laptop', keywords: 'computer work code' },
+            { emoji: '📧', name: 'Email', keywords: 'mail inbox' },
+            { emoji: '📅', name: 'Calendar', keywords: 'date plan schedule' },
+            { emoji: '📝', name: 'Memo', keywords: 'notes write journal' },
+            { emoji: '✅', name: 'Check mark', keywords: 'done task todo' },
+            { emoji: '📋', name: 'Clipboard', keywords: 'list checklist' },
+            { emoji: '📚', name: 'Books', keywords: 'read study learn' },
+            { emoji: '📖', name: 'Open book', keywords: 'read' },
+            { emoji: '🎓', name: 'Graduation cap', keywords: 'study school learn' },
+            { emoji: '✏️', name: 'Pencil', keywords: 'write draw' },
+            { emoji: '🎯', name: 'Bullseye', keywords: 'goal focus target' },
+            { emoji: '💡', name: 'Light bulb', keywords: 'idea' },
+            { emoji: '🧾', name: 'Receipt', keywords: 'bills budget' },
+            { emoji: '💰', name: 'Money bag', keywords: 'finance budget savings' },
+        ],
+    },
+    {
+        label: 'Play and music',
+        emojis: [
+            { emoji: '🎵', name: 'Musical note', keywords: 'music song' },
+            { emoji: '🎧', name: 'Headphones', keywords: 'music podcast listen' },
+            { emoji: '🎸', name: 'Guitar', keywords: 'music practice' },
+            { emoji: '🎹', name: 'Piano keyboard', keywords: 'music practice' },
+            { emoji: '🎨', name: 'Artist palette', keywords: 'paint draw art' },
+            { emoji: '🎮', name: 'Video game', keywords: 'play controller' },
+            { emoji: '📺', name: 'Television', keywords: 'tv watch show' },
+            { emoji: '🎬', name: 'Clapper board', keywords: 'movie film' },
+            { emoji: '📷', name: 'Camera', keywords: 'photo picture' },
+            { emoji: '🧩', name: 'Puzzle piece', keywords: 'game' },
+        ],
+    },
+    {
+        label: 'Outside and travel',
+        emojis: [
+            { emoji: '🚶', name: 'Person walking', keywords: 'walk steps' },
+            { emoji: '🥾', name: 'Hiking boot', keywords: 'hike trail' },
+            { emoji: '🌳', name: 'Tree', keywords: 'park nature' },
+            { emoji: '⛰️', name: 'Mountain', keywords: 'hike' },
+            { emoji: '🌧️', name: 'Rain cloud', keywords: 'weather' },
+            { emoji: '❄️', name: 'Snowflake', keywords: 'winter cold' },
+            { emoji: '🚗', name: 'Car', keywords: 'drive commute' },
+            { emoji: '🚌', name: 'Bus', keywords: 'commute transit' },
+            { emoji: '✈️', name: 'Airplane', keywords: 'travel flight trip' },
+            { emoji: '🧳', name: 'Luggage', keywords: 'travel pack trip' },
+        ],
+    },
+    {
+        label: 'Symbols',
+        emojis: [
+            { emoji: '⭐', name: 'Star', keywords: 'favorite' },
+            { emoji: '✨', name: 'Sparkles', keywords: 'new clean' },
+            { emoji: '🔥', name: 'Fire', keywords: 'streak hot' },
+            { emoji: '🎉', name: 'Party popper', keywords: 'celebrate' },
+            { emoji: '🏆', name: 'Trophy', keywords: 'win goal' },
+            { emoji: '🔔', name: 'Bell', keywords: 'reminder notify' },
+            { emoji: '⏱️', name: 'Stopwatch', keywords: 'timer time' },
+            { emoji: '⏳', name: 'Hourglass', keywords: 'wait time' },
+            { emoji: '🔄', name: 'Counterclockwise arrows', keywords: 'repeat again refresh' },
+            { emoji: '🙏', name: 'Folded hands', keywords: 'gratitude thanks pray' },
+            { emoji: '😊', name: 'Smiling face', keywords: 'happy' },
+            { emoji: '🌈', name: 'Rainbow', keywords: 'colour' },
+        ],
+    },
+];
+export function filterEmojiGroups(query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return EMOJI_GROUPS;
+    return EMOJI_GROUPS.map((group) => ({
+        ...group,
+        emojis: group.emojis.filter((e) => `${e.name} ${e.keywords ?? ''}`.toLowerCase().includes(q)),
+    })).filter((group) => group.emojis.length > 0);
+}

package/dist/components/app/emoji-field.d.ts

@@ -0,0 +1,23 @@
+export type EmojiFieldProps = {
+    /** The trigger button's id, for the field's `<FieldLabel htmlFor>`. */
+    id?: string;
+    /** The emoji, or `''` for none. */
+    value: string;
+    /** Called with the picked emoji, or `''` when cleared. */
+    onChange: (value: string) => void;
+    /** What the button says with none picked. Defaults to "Pick an emoji". */
+    placeholder?: string;
+    /** Offer Clear in the popup, for an optional field. */
+    clearable?: boolean;
+    /** The value was refused: `aria-invalid` on the button. */
+    invalid?: boolean;
+    /** Saving: the button shows the emoji but won't open. */
+    readOnly?: boolean;
+    /** Open on mount (for stories and editing in place). */
+    defaultOpen?: boolean;
+    className?: string;
+    'aria-label'?: string;
+    'aria-labelledby'?: string;
+    'aria-describedby'?: string;
+};
+export declare function EmojiField({ id, value, onChange, placeholder, clearable, invalid, readOnly, defaultOpen, className, ...aria }: EmojiFieldProps): import("react").JSX.Element;

package/dist/components/app/emoji-field.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// One emoji on a form: a routine's mark, a list's icon. The value is the
+// emoji itself, or `''` for none. A button showing the choice, opening a
+// Popover with a search box and a curated set of emoji in groups (not the
+// whole of Unicode: `emoji-field-data.ts`). Like DateField it is one
+// control for a react-hook-form `Controller`; `clearable` adds Clear.
+import { useState } from 'react';
+import { SmilePlus } from 'lucide-react';
+import { cn } from 'cn';
+import { Button } from '../ui/button.js';
+import { Input } from '../ui/input.js';
+import { Popover, PopoverContent, PopoverTrigger } from '../ui/popover.js';
+import { filterEmojiGroups } from './emoji-field-data.js';
+export function EmojiField({ id, value, onChange, placeholder = 'Pick an emoji', clearable = false, invalid = false, readOnly = false, defaultOpen = false, className, ...aria }) {
+    const [open, setOpen] = useState(defaultOpen && !readOnly);
+    const [query, setQuery] = useState('');
+    const groups = filterEmojiGroups(query);
+    const changeOpen = (next) => {
+        if (next && readOnly)
+            return;
+        setOpen(next);
+        if (!next)
+            setQuery('');
+    };
+    const pick = (next) => {
+        onChange(next);
+        changeOpen(false);
+    };
+    return (_jsxs(Popover, { open: open, onOpenChange: changeOpen, children: [_jsx(PopoverTrigger, { render: _jsx(Button, { id: id, type: "button", variant: "outline", "aria-invalid": invalid || undefined, "aria-readonly": readOnly || undefined, className: cn('w-full justify-start font-normal', !value && 'text-muted-foreground', className), ...aria }), children: value ? (_jsx("span", { className: "text-base leading-none", children: value })) : (_jsxs(_Fragment, { children: [_jsx(SmilePlus, { "aria-hidden": "true", className: "size-4" }), placeholder] })) }), _jsxs(PopoverContent, { className: "w-72 gap-2 p-2", align: "start", "data-slot": "emoji-field-popup", "aria-label": "Emoji", children: [_jsx(Input, { type: "search", autoComplete: "off", "aria-label": "Search emoji", placeholder: "Search", value: query, onChange: (event) => setQuery(event.target.value) }), _jsx("div", { className: "max-h-64 overflow-y-auto", children: groups.length === 0 ? (_jsxs("p", { className: "p-2 text-sm text-muted-foreground", children: ["No emoji match \"", query.trim(), "\"."] })) : (groups.map((group) => (_jsxs("section", { "aria-label": group.label, className: "mb-2 last:mb-0", children: [_jsx("h3", { className: "px-1 py-1 text-xs font-medium text-muted-foreground", children: group.label }), _jsx("div", { className: "grid grid-cols-7 gap-0.5", children: group.emojis.map((entry) => (_jsx("button", { type: "button", "aria-label": entry.name, title: entry.name, "aria-pressed": entry.emoji === value, onClick: () => pick(entry.emoji), className: "flex size-8 items-center justify-center rounded-md text-xl leading-none outline-none hover:bg-muted focus-visible:ring-3 focus-visible:ring-ring/50 aria-pressed:bg-accent", children: entry.emoji }, entry.emoji))) })] }, group.label)))) }), clearable && value && (_jsx("div", { className: "border-t border-border pt-2", children: _jsx(Button, { type: "button", variant: "ghost", size: "sm", className: "w-full", onClick: () => pick(''), children: "Clear" }) }))] })] }));
+}

package/dist/components/app/line-chart.d.ts

@@ -10,6 +10,15 @@ export type LineChartProps = {
         y: number;
         label: string;
     };
+    /**
+     * Where the line may go next, drawn dashed on from its last point:
+     * `{ label: 'Projected', points }`, oldest first, each after the last of
+     * `points`. The mark is only ever on `points`.
+     */
+    projection?: {
+        label: string;
+        points: readonly LineChartPoint[];
+    };
     /** Which point to mark with a dot and its value: the lowest, the highest or the latest. */
     mark?: LineChartMark;
     /** A value as shown: `usd`. Defaults to the number as the browser writes it. */
@@ -23,4 +32,4 @@ export type LineChartProps = {
     emptyMessage?: string;
     className?: string;
 };
-export declare function LineChart({ label, points, target, mark, formatY, formatX, height, isLoading, emptyMessage, className, }: LineChartProps): import("react").JSX.Element;
+export declare function LineChart({ label, points, target, projection, mark, formatY, formatX, height, isLoading, emptyMessage, className, }: LineChartProps): import("react").JSX.Element;

package/dist/components/app/line-chart.js

@@ -13,7 +13,12 @@ import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-run
 //
 // The picture is for the eye: a screen reader gets the figure's name,
 // a summary (first, last, lowest, highest, the target) and a table of
-// every point, all visually hidden. The four states: a skeleton at
+// every point, all visually hidden.
+//
+// A `projection` (4.51) carries the line on past its last point, dashed in
+// the same colour: where a balance may go, not where it went. It shares
+// the plot's x and y ranges, so the target and the projection meet where
+// they would. The four states: a skeleton at
 // `height` while loading, one quiet line with no points, a dot (no line)
 // for one point, and the chart.
 import { cn } from 'cn';
@@ -29,18 +34,21 @@ const PLATE = 'rounded-sm bg-card px-1';
 function besides(x) {
     return x > 0.75 ? '-translate-x-full -ml-1.5' : 'ml-1.5';
 }
-export function LineChart({ label, points, target, mark, formatY = defaultY, formatX = defaultX, height = 160, isLoading = false, emptyMessage = 'No points yet', className, }) {
+export function LineChart({ label, points, target, projection, mark, formatY = defaultY, formatX = defaultX, height = 160, isLoading = false, emptyMessage = 'No points yet', className, }) {
     if (isLoading) {
         return (_jsxs("div", { "data-slot": "line-chart", "data-state": "loading", "aria-busy": "true", className: cn('min-w-0', className), children: [_jsxs("span", { className: "sr-only", children: ["Loading ", label] }), _jsx(Skeleton, { style: { height }, className: "w-full" })] }));
     }
     if (points.length === 0) {
         return (_jsx("figure", { "data-slot": "line-chart", "data-state": "empty", "aria-label": label, className: cn('min-w-0', className), children: _jsx("p", { style: { height }, className: "flex items-center justify-center rounded-md border border-dashed border-border type-body text-muted-foreground", children: emptyMessage }) }));
     }
-    const layout = chartLayout(points, target?.y, mark);
+    const ahead = projection?.points ?? [];
+    const layout = { ...chartLayout([...points, ...ahead], target?.y), markIndex: chartLayout(points, undefined, mark).markIndex };
+    const projected = ahead.length > 0 ? layout.places.slice(points.length - 1) : [];
+    const lastX = ahead.length > 0 ? ahead[ahead.length - 1].x : points[points.length - 1].x;
     const values = points.map((point) => point.y);
     const lowest = values.indexOf(Math.min(...values));
     const highest = values.indexOf(Math.max(...values));
-    const line = layout.places.map((place) => `${place.x * 100},${place.y * 100}`).join(' ');
+    const line = layout.places.slice(0, points.length).map((place) => `${place.x * 100},${place.y * 100}`).join(' ');
     const marked = layout.markIndex === undefined ? undefined : layout.places[layout.markIndex];
     const single = points.length === 1 ? layout.places[0] : undefined;
     const dot = marked ?? single;
@@ -49,11 +57,12 @@ export function LineChart({ label, points, target, mark, formatY = defaultY, for
         points.length === 1 ? `One point: ${describe(0)}` : `From ${describe(0)} to ${describe(points.length - 1)}`,
         points.length > 2 && `lowest ${describe(lowest)}`,
         points.length > 2 && `highest ${describe(highest)}`,
+        projection && ahead.length > 0 && `${projection.label} ${formatY(ahead[ahead.length - 1].y)} on ${formatX(lastX)}`,
         target && `${target.label} ${formatY(target.y)}`,
     ]
         .filter(Boolean)
         .join('; ');
-    return (_jsxs("figure", { "data-slot": "line-chart", "data-state": "success", "aria-label": label, className: cn('flex min-w-0 flex-col gap-1.5', className), children: [_jsxs("div", { "aria-hidden": "true", className: "relative border-b border-border", style: { height }, children: [target && layout.targetY !== undefined && (_jsxs(_Fragment, { children: [_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "absolute inset-0 size-full overflow-visible text-success-text", children: _jsx("line", { x1: "0", x2: "100", y1: layout.targetY * 100, y2: layout.targetY * 100, strokeWidth: 1.5, strokeDasharray: "6 4", vectorEffect: "non-scaling-stroke", className: "stroke-current" }) }), _jsxs("span", { className: cn('absolute right-0 -translate-y-full type-caption text-success-text tabular-nums', PLATE), style: { top: percent(layout.targetY) }, children: [target.label, " ", formatY(target.y)] })] })), points.length > 1 && (_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "absolute inset-0 size-full overflow-visible text-info-text", children: _jsx("polyline", { points: line, fill: "none", strokeWidth: 2, strokeLinejoin: "round", strokeLinecap: "round", vectorEffect: "non-scaling-stroke", className: "stroke-current" }) })), dot && (_jsxs(_Fragment, { children: [_jsx("span", { "data-slot": "line-chart-mark", className: "absolute size-2.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-info-text ring-2 ring-card", style: { left: percent(dot.x), top: percent(dot.y) } }), _jsx("span", { className: cn('absolute type-caption font-medium text-foreground tabular-nums', PLATE, besides(dot.x), 
+    return (_jsxs("figure", { "data-slot": "line-chart", "data-state": "success", "aria-label": label, className: cn('flex min-w-0 flex-col gap-1.5', className), children: [_jsxs("div", { "aria-hidden": "true", className: "relative border-b border-border", style: { height }, children: [target && layout.targetY !== undefined && (_jsxs(_Fragment, { children: [_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "absolute inset-0 size-full overflow-visible text-success-text", children: _jsx("line", { x1: "0", x2: "100", y1: layout.targetY * 100, y2: layout.targetY * 100, strokeWidth: 1.5, strokeDasharray: "6 4", vectorEffect: "non-scaling-stroke", className: "stroke-current" }) }), _jsxs("span", { className: cn('absolute right-0 -translate-y-full type-caption text-success-text tabular-nums', PLATE), style: { top: percent(layout.targetY) }, children: [target.label, " ", formatY(target.y)] })] })), points.length > 1 && (_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "absolute inset-0 size-full overflow-visible text-info-text", children: _jsx("polyline", { points: line, fill: "none", strokeWidth: 2, strokeLinejoin: "round", strokeLinecap: "round", vectorEffect: "non-scaling-stroke", className: "stroke-current" }) })), projected.length > 1 && (_jsx("svg", { "data-slot": "line-chart-projection", viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "absolute inset-0 size-full overflow-visible text-info-text", children: _jsx("polyline", { points: projected.map((place) => `${place.x * 100},${place.y * 100}`).join(' '), fill: "none", strokeWidth: 2, strokeDasharray: "6 4", strokeLinejoin: "round", vectorEffect: "non-scaling-stroke", className: "stroke-current" }) })), dot && (_jsxs(_Fragment, { children: [_jsx("span", { "data-slot": "line-chart-mark", className: "absolute size-2.5 -translate-x-1/2 -translate-y-1/2 rounded-full bg-info-text ring-2 ring-card", style: { left: percent(dot.x), top: percent(dot.y) } }), _jsx("span", { className: cn('absolute type-caption font-medium text-foreground tabular-nums', PLATE, besides(dot.x), 
                                 // Under the lowest point, where the line isn't; over any other.
-                                mark === 'min' ? 'mt-1' : '-translate-y-full -mt-1'), style: { left: percent(dot.x), top: percent(dot.y) }, children: formatY(points[marked ? layout.markIndex : 0].y) })] }))] }), _jsxs("div", { "aria-hidden": "true", className: "flex justify-between gap-3 type-caption text-muted-foreground tabular-nums", children: [_jsx("span", { children: formatX(points[0].x) }), points.length > 1 && _jsx("span", { children: formatX(points[points.length - 1].x) })] }), _jsx("figcaption", { className: "sr-only", children: summary }), _jsxs("table", { className: "sr-only", children: [_jsx("caption", { children: label }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "When" }), _jsx("th", { scope: "col", children: "Value" })] }) }), _jsx("tbody", { children: points.map((point, index) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: formatX(point.x) }), _jsx("td", { children: formatY(point.y) })] }, index))) })] })] }));
+                                mark === 'min' ? 'mt-1' : '-translate-y-full -mt-1'), style: { left: percent(dot.x), top: percent(dot.y) }, children: formatY(points[marked ? layout.markIndex : 0].y) })] }))] }), _jsxs("div", { "aria-hidden": "true", className: "flex justify-between gap-3 type-caption text-muted-foreground tabular-nums", children: [_jsx("span", { children: formatX(points[0].x) }), (points.length > 1 || ahead.length > 0) && _jsx("span", { children: formatX(lastX) })] }), _jsx("figcaption", { className: "sr-only", children: summary }), _jsxs("table", { className: "sr-only", children: [_jsx("caption", { children: label }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "When" }), _jsx("th", { scope: "col", children: "Value" })] }) }), _jsxs("tbody", { children: [points.map((point, index) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: formatX(point.x) }), _jsx("td", { children: formatY(point.y) })] }, index))), ahead.map((point, index) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: formatX(point.x) }), _jsxs("td", { children: [formatY(point.y), " (", projection.label, ")"] })] }, `ahead-${index}`)))] })] })] }));
 }

package/dist/components/app/multi-line-chart.d.ts

@@ -0,0 +1,34 @@
+import { type LineChartPoint } from '../../lib/line-chart-layout.js';
+export type ChartTone = 'info' | 'success' | 'warning' | 'destructive' | 'muted';
+export type ChartSeries = {
+    /** The series' name in the legend and the table: "Net worth". */
+    label: string;
+    /** Its values, oldest first. */
+    points: readonly LineChartPoint[];
+    /** Its colour, a text tone that clears 3:1 on a card. Defaults to `info`. */
+    tone?: ChartTone;
+    /** Dashed: a projection or a plan, not something measured. */
+    dashed?: boolean;
+};
+export type MultiLineChartProps = {
+    /** The figure's name: "Net worth over time". */
+    label: string;
+    /** The series, drawn in this order (the last on top) and listed in the legend. */
+    series: readonly ChartSeries[];
+    /** A dashed line at a value to reach: `{ y: 1_500_000, label: 'Target' }`, in `success-text`. */
+    target?: {
+        y: number;
+        label: string;
+    };
+    /** A value as shown: `usd`. Defaults to the number as the browser writes it. */
+    formatY?: (y: number) => string;
+    /** A point's x as shown: `formatPlainDate`. Defaults to x as given. */
+    formatX?: (x: LineChartPoint['x']) => string;
+    /** The plot's height in px; the chart fills its container's width. */
+    height?: number;
+    isLoading?: boolean;
+    /** What shows when no series has a point. */
+    emptyMessage?: string;
+    className?: string;
+};
+export declare function MultiLineChart({ label, series, target, formatY, formatX, height, isLoading, emptyMessage, className, }: MultiLineChartProps): import("react").JSX.Element;

package/dist/components/app/multi-line-chart.js

@@ -0,0 +1,75 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+// Several values over time on one plot (4.51): a net worth beside its
+// assets and debts, or a balance's history beside low, middle and high
+// projections. LineChart's sibling, plain SVG the same way: each series is
+// its own <svg> drawing in currentColor in a text tone, so the package's
+// glyph check measures it like any icon, and a dashed series (a
+// projection, a plan) reads apart from a solid one in either theme. A
+// legend under the plot names each series with its latest value, so the
+// colours never carry the meaning alone.
+//
+// The picture is for the eye: a screen reader gets the figure's name, a
+// summary (each series from its first to its last value, the target) and
+// a table with a column per series, all visually hidden. The four states:
+// a skeleton at `height` while loading, one quiet line when no series has
+// a point, a dot for a series of one point, and the chart.
+import { cn } from 'cn';
+import { Skeleton } from '../ui/skeleton.js';
+import { seriesLayout } from '../../lib/line-chart-layout.js';
+const TONE = {
+    info: 'text-info-text',
+    success: 'text-success-text',
+    warning: 'text-warning-text',
+    destructive: 'text-destructive-text',
+    muted: 'text-muted-foreground',
+};
+const DOT = {
+    info: 'bg-info-text',
+    success: 'bg-success-text',
+    warning: 'bg-warning-text',
+    destructive: 'bg-destructive-text',
+    muted: 'bg-muted-foreground',
+};
+const defaultY = (y) => y.toLocaleString();
+const defaultX = (x) => String(x);
+const percent = (fraction) => `${fraction * 100}%`;
+const DASH = '6 4';
+export function MultiLineChart({ label, series, target, formatY = defaultY, formatX = defaultX, height = 160, isLoading = false, emptyMessage = 'No points yet', className, }) {
+    if (isLoading) {
+        return (_jsxs("div", { "data-slot": "multi-line-chart", "data-state": "loading", "aria-busy": "true", className: cn('min-w-0', className), children: [_jsxs("span", { className: "sr-only", children: ["Loading ", label] }), _jsx(Skeleton, { style: { height }, className: "w-full" })] }));
+    }
+    const drawn = series.filter((one) => one.points.length > 0);
+    if (drawn.length === 0) {
+        return (_jsx("figure", { "data-slot": "multi-line-chart", "data-state": "empty", "aria-label": label, className: cn('min-w-0', className), children: _jsx("p", { style: { height }, className: "flex items-center justify-center rounded-md border border-dashed border-border type-body text-muted-foreground", children: emptyMessage }) }));
+    }
+    const layout = seriesLayout(drawn.map((one) => one.points), target?.y);
+    // The x range's two ends, by where they sit on the plot.
+    const ends = drawn.flatMap((one, s) => one.points.map((point, p) => ({ x: point.x, at: layout.places[s][p].x })));
+    const left = ends.reduce((a, b) => (b.at < a.at ? b : a));
+    const right = ends.reduce((a, b) => (b.at > a.at ? b : a));
+    // Every x once, in order along the plot, for the table's rows.
+    const rows = [...new Map(ends.sort((a, b) => a.at - b.at).map((end) => [String(end.x), end.x])).values()];
+    const summary = [
+        ...drawn.map((one) => {
+            const first = one.points[0];
+            const last = one.points[one.points.length - 1];
+            return one.points.length === 1
+                ? `${one.label}: ${formatY(first.y)} on ${formatX(first.x)}`
+                : `${one.label} from ${formatY(first.y)} on ${formatX(first.x)} to ${formatY(last.y)} on ${formatX(last.x)}`;
+        }),
+        target && `${target.label} ${formatY(target.y)}`,
+    ]
+        .filter(Boolean)
+        .join('; ');
+    return (_jsxs("figure", { "data-slot": "multi-line-chart", "data-state": "success", "aria-label": label, className: cn('flex min-w-0 flex-col gap-1.5', className), children: [_jsxs("div", { "aria-hidden": "true", className: "relative border-b border-border", style: { height }, children: [target && layout.targetY !== undefined && (_jsxs(_Fragment, { children: [_jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "absolute inset-0 size-full overflow-visible text-success-text", children: _jsx("line", { x1: "0", x2: "100", y1: layout.targetY * 100, y2: layout.targetY * 100, strokeWidth: 1.5, strokeDasharray: DASH, vectorEffect: "non-scaling-stroke", className: "stroke-current" }) }), _jsxs("span", { className: "absolute right-0 -translate-y-full rounded-sm bg-card px-1 type-caption text-success-text tabular-nums", style: { top: percent(layout.targetY) }, children: [target.label, " ", formatY(target.y)] })] })), drawn.map((one, s) => {
+                        const tone = one.tone ?? 'info';
+                        const places = layout.places[s];
+                        if (places.length === 1) {
+                            return (_jsx("span", { "data-slot": "multi-line-chart-dot", className: cn('absolute size-2.5 -translate-x-1/2 -translate-y-1/2 rounded-full ring-2 ring-card', DOT[tone]), style: { left: percent(places[0].x), top: percent(places[0].y) } }, s));
+                        }
+                        return (_jsx("svg", { "data-slot": "multi-line-chart-series", viewBox: "0 0 100 100", preserveAspectRatio: "none", className: cn('absolute inset-0 size-full overflow-visible', TONE[tone]), children: _jsx("polyline", { points: places.map((place) => `${place.x * 100},${place.y * 100}`).join(' '), fill: "none", strokeWidth: 2, strokeDasharray: one.dashed ? DASH : undefined, strokeLinejoin: "round", strokeLinecap: one.dashed ? undefined : 'round', vectorEffect: "non-scaling-stroke", className: "stroke-current" }) }, s));
+                    })] }), _jsxs("div", { "aria-hidden": "true", className: "flex justify-between gap-3 type-caption text-muted-foreground tabular-nums", children: [_jsx("span", { children: formatX(left.x) }), right.at > left.at && _jsx("span", { children: formatX(right.x) })] }), _jsx("ul", { "aria-hidden": "true", "data-slot": "multi-line-chart-legend", className: "flex flex-wrap gap-x-4 gap-y-1 type-caption text-foreground", children: drawn.map((one, s) => (_jsxs("li", { className: "flex items-center gap-1.5", children: [_jsx("svg", { viewBox: "0 0 16 4", className: cn('h-1 w-4 shrink-0', TONE[one.tone ?? 'info']), children: _jsx("line", { x1: "0", x2: "16", y1: "2", y2: "2", strokeWidth: 2, strokeDasharray: one.dashed ? '4 2' : undefined, className: "stroke-current" }) }), _jsx("span", { children: one.label }), _jsx("span", { className: "font-medium tabular-nums", children: formatY(one.points[one.points.length - 1].y) })] }, s))) }), _jsx("figcaption", { className: "sr-only", children: summary }), _jsxs("table", { className: "sr-only", children: [_jsx("caption", { children: label }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "When" }), drawn.map((one, s) => (_jsx("th", { scope: "col", children: one.label }, s)))] }) }), _jsx("tbody", { children: rows.map((x) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: formatX(x) }), drawn.map((one, s) => {
+                                    const point = one.points.find((p) => String(p.x) === String(x));
+                                    return _jsx("td", { children: point ? formatY(point.y) : '' }, s);
+                                })] }, String(x)))) })] })] }));
+}

package/dist/index.d.ts

@@ -37,9 +37,11 @@ export { Notice, type NoticeProps, type NoticeTone } from './components/app/noti
 export { SourceCredit, type Source, type SourceCreditProps } from './components/app/source-credit.js';
 export { ProgressRing, type ProgressRingProps } from './components/app/progress-ring.js';
 export { LineChart, type LineChartMark, type LineChartPoint, type LineChartProps, } from './components/app/line-chart.js';
+export { MultiLineChart, type ChartSeries, type ChartTone, type MultiLineChartProps, } from './components/app/multi-line-chart.js';
 export { StepBar, type StepBarProps } from './components/app/step-bar.js';
 export { RatingStar, type RatingStarProps, type RatingStarValue } from './components/app/rating-star.js';
 export { DateField, type DateFieldProps } from './components/app/date-field.js';
+export { EmojiField, type EmojiFieldProps } from './components/app/emoji-field.js';
 export { ImageField, type ImageFieldProps } from './components/app/image-field.js';
 export { DEFAULT_IMAGE_TYPES, type ImageUpload, type ImageUploadResult } from './lib/image-file.js';
 export { formatPlainDate, type PlainDate } from './lib/plain-date.js';

package/dist/index.js

@@ -40,9 +40,11 @@ export { Notice } from './components/app/notice.js';
 export { SourceCredit } from './components/app/source-credit.js';
 export { ProgressRing } from './components/app/progress-ring.js';
 export { LineChart, } from './components/app/line-chart.js';
+export { MultiLineChart, } from './components/app/multi-line-chart.js';
 export { StepBar } from './components/app/step-bar.js';
 export { RatingStar } from './components/app/rating-star.js';
 export { DateField } from './components/app/date-field.js';
+export { EmojiField } from './components/app/emoji-field.js';
 export { ImageField } from './components/app/image-field.js';
 export { DEFAULT_IMAGE_TYPES } from './lib/image-file.js';
 export { formatPlainDate } from './lib/plain-date.js';

package/dist/lib/line-chart-layout.d.ts

@@ -21,3 +21,16 @@ export type ChartLayout = {
     markIndex?: number;
 };
 export declare function chartLayout(points: readonly LineChartPoint[], target?: number, mark?: LineChartMark): ChartLayout;
+export type SeriesLayout = {
+    /** Each series' places, in the order given, each in its points' order. */
+    places: {
+        x: number;
+        y: number;
+    }[][];
+    domain: {
+        min: number;
+        max: number;
+    };
+    targetY?: number;
+};
+export declare function seriesLayout(series: readonly (readonly LineChartPoint[])[], target?: number): SeriesLayout;

package/dist/lib/line-chart-layout.js

@@ -42,3 +42,27 @@ export function chartLayout(points, target, mark) {
         markIndex,
     };
 }
+// Several series on one plot (MultiLineChart): one y range over all their
+// values and the target, and one x range over all their points, so a
+// series that starts later starts further right. When an x isn't a time
+// or a number, each series' points are evenly spaced over the longest's.
+export function seriesLayout(series, target) {
+    const shared = chartLayout(series.flat(), target);
+    const { min, max } = shared.domain;
+    const height = (y) => (max - y) / (max - min);
+    const times = series.flat().map((point) => along(point.x));
+    const timed = times.every(Number.isFinite) && new Set(times).size > 1;
+    const first = Math.min(...times);
+    const span = Math.max(...times) - first;
+    const longest = Math.max(...series.map((points) => points.length - 1));
+    const across = (x, index) => {
+        if (timed)
+            return (along(x) - first) / span;
+        return longest === 0 ? 0.5 : index / longest;
+    };
+    return {
+        places: series.map((points) => points.map((point, index) => ({ x: across(point.x, index), y: height(point.y) }))),
+        domain: shared.domain,
+        targetY: shared.targetY,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tristan2828/ui-foundation",
-  "version": "4.50.1",
+  "version": "4.52.0",
   "description": "Shared UI foundation for contract-first, database-backed React apps: shadcn primitives, DataTable/EntityForm composites, auth, the gateway error seam, design tokens, lint rules and the AI playbook.",
   "license": "MIT",
   "repository": {