@twentyfirstmedia/ui-core 0.7.0 → 0.8.0

package/src/components/types.ts

@@ -2990,6 +2990,10 @@ export interface ConsentScope {
   granted: boolean;
   /** Needed for the connection to work at all: shown, not switchable. */
   required?: boolean;
+  /** What the permission allows: reading, acting (sending, booking, switching) or moving money. */
+  level?: "read" | "act" | "money";
+  /** The assistant asks you before it uses this permission. */
+  asksFirst?: boolean;
 }
 export interface ConsentConnector {
   id: string;
@@ -3155,3 +3159,279 @@ export interface DocumentListProps extends BaseProps {
   /** Accessible name (default "Documents"). */
   label?: string;
 }
+
+/* ── Connectors: services an assistant reads from and acts in ── */
+/** The state of a connected service. */
+export type ServiceState = "connected" | "syncing" | "error" | "paused" | "off";
+export interface ServiceMarkProps extends BaseProps {
+  /** The service's name: the accessible name, and the monogram when there is no icon or logo. */
+  name: string;
+  /** A brand logo (`brandGmail` …) or a line icon. */
+  icon?: IconName;
+  /** Your own logo (an `<img>` or `<svg>`) instead of the icon. */
+  logo?: ReactNode;
+  /** Letters for the monogram (default: the initials of `name`). */
+  monogram?: string;
+  /** 24, 36 (default) or 48 px. */
+  size?: "sm" | "md" | "lg";
+  tint?: Tint | "plain";
+  /** A dot in the corner with the state in words for screen readers. */
+  status?: ServiceState;
+  /** Hidden from screen readers when the name is written next to it. */
+  decorative?: boolean;
+}
+export interface Connector {
+  id: string;
+  name: string;
+  icon?: IconName;
+  logo?: ReactNode;
+  /** Letters shown when there is neither icon nor logo (default: the initials of `name`). */
+  monogram?: string;
+  tint?: Tint | "plain";
+  /** The group it is listed under ("Health & fitness", "Money" …). */
+  category: string;
+  description?: ReactNode;
+  /** `available` (default), `connected`, `error` (needs a reconnect) or `soon`. */
+  state?: "available" | "connected" | "error" | "soon";
+  /** A hint under the description: "Needs the iPhone app", "Import an export file". */
+  note?: ReactNode;
+  /** The connected account ("mara@gmail.com"). */
+  account?: string;
+}
+export interface ConnectorGalleryProps extends BaseProps {
+  connectors: Connector[];
+  /** Order of the groups; categories not listed follow in the order they appear. */
+  categories?: string[];
+  onConnect?: (id: string) => void;
+  /** Opens a connected (or failing) connector. */
+  onOpen?: (id: string) => void;
+  /** A search field and category chips above the grid (default true). */
+  filters?: boolean;
+  /** Accessible name (default "Connectors"). */
+  label?: string;
+}
+export interface SyncStatusProps extends BaseProps {
+  state: "synced" | "syncing" | "error" | "paused" | "never";
+  /** The last successful sync. */
+  last?: Date | string | number;
+  /** The next planned sync. */
+  next?: Date | string | number;
+  /** "Now" for the relative times; pass it so server and client render the same. */
+  now?: Date | string | number;
+  /** What the last sync brought: `{ label: "emails", value: 1204 }`. */
+  counts?: { label: string; value: number }[];
+  /** Why the sync failed. */
+  error?: ReactNode;
+  onSync?: () => void;
+  /** One line: state and time only. */
+  compact?: boolean;
+}
+export interface AgentAction {
+  id: string;
+  /** The service the action used. */
+  service?: { name: string; icon?: IconName; logo?: ReactNode };
+  /** Which agent did it ("Assistant", "Money agent"). */
+  agent?: string;
+  /** What happened, in a sentence: "Moved the dentist to Friday, 10:00". */
+  text: ReactNode;
+  at: Date | string | number;
+  /** `read` (looked something up), `act` (changed something) or `money`. */
+  kind?: "read" | "act" | "money";
+  /** `done` (default), `waiting` for your approval, `declined`, `undone` or `failed`. */
+  state?: "done" | "waiting" | "declined" | "undone" | "failed";
+  detail?: ReactNode;
+}
+export interface AgentActivityProps extends BaseProps {
+  items: AgentAction[];
+  /** "Now" for the day headings; pass it so server and client render the same. */
+  now?: Date | string | number;
+  /** Offers "Undo" on finished actions that changed something. */
+  onUndo?: (id: string) => void;
+  /** Opens an action that waits for your approval. */
+  onReview?: (id: string) => void;
+  /** Accessible name (default "Agent activity"). */
+  label?: string;
+}
+export interface ConnectionItem {
+  id: string;
+  name: string;
+  icon?: IconName;
+  logo?: ReactNode;
+  monogram?: string;
+  tint?: Tint | "plain";
+  /** The connected account ("mara@gmail.com", "Giro ••• 4410"). */
+  account?: ReactNode;
+  state: ServiceState;
+  /** How fresh the data is, shown as a compact `SyncStatus`. */
+  sync?: { state: SyncStatusProps["state"]; last?: Date | string | number };
+}
+export interface ConnectionListProps extends BaseProps {
+  items: ConnectionItem[];
+  /** "Now" for the relative times; pass it so server and client render the same. */
+  now?: Date | string | number;
+  onManage?: (id: string) => void;
+  /** Shown instead of "Manage" on connections in the `error` state. */
+  onReconnect?: (id: string) => void;
+  /** Accessible name (default "Connections"). */
+  label?: string;
+}
+
+/* ── Connected data: home, car, media, workouts, calls, bookings, golf, investments ── */
+/** The service a value comes from, shown as a small mark. */
+export interface ServiceRef {
+  name: string;
+  icon?: IconName;
+  logo?: ReactNode;
+}
+export interface DeviceTileProps extends BaseProps {
+  name: string;
+  room?: string;
+  icon?: IconName;
+  /** The kind sets the default icon and which controls appear. */
+  kind?: "switch" | "light" | "thermostat" | "vacuum" | "purifier" | "camera" | "lock" | "sensor";
+  /** On or off; with `onToggle` a switch. */
+  on?: boolean;
+  onToggle?: (on: boolean) => void;
+  /** The main reading: "21.5 °C", "Cleaning", "AQI 12". */
+  value?: ReactNode;
+  /** A line under the value: "Heating to 22 °C", "Kitchen · 18 m² left". */
+  status?: ReactNode;
+  /** Thermostat target in °C; with `onTarget` a − / + stepper (steps of `step`, default 0.5). */
+  target?: number;
+  onTarget?: (value: number) => void;
+  step?: number;
+  /** Battery in percent (vacuums, sensors, locks). */
+  battery?: number;
+  /** Quick actions: "Start", "Dock", "Boost". */
+  actions?: { label: string; icon?: IconName; onClick?: () => void }[];
+  /** The device does not answer. */
+  offline?: boolean;
+  service?: ServiceRef;
+}
+export interface VehicleCardProps extends BaseProps {
+  name: string;
+  model?: string;
+  /** Battery (or tank) in percent. */
+  battery: number;
+  /** Range in km. */
+  range?: number;
+  /** The charge limit in percent, marked on the bar. */
+  limit?: number;
+  charging?: "charging" | "complete" | "plugged" | "unplugged";
+  /** Charging power in kW while charging. */
+  power?: number;
+  /** When charging reaches the limit. */
+  until?: Date | string | number;
+  locked?: boolean;
+  /** Inside temperature in °C. */
+  inside?: number;
+  climateOn?: boolean;
+  location?: ReactNode;
+  onLock?: (locked: boolean) => void;
+  onClimate?: (on: boolean) => void;
+  service?: ServiceRef;
+}
+export interface NowPlayingProps extends BaseProps {
+  title: string;
+  artist?: string;
+  album?: string;
+  /** Cover art: an `<img>`. */
+  art?: ReactNode;
+  /** Position and length in seconds. */
+  position?: number;
+  duration?: number;
+  playing?: boolean;
+  /** Where it plays: "Living room speaker". */
+  device?: string;
+  onPlayPause?: () => void;
+  onNext?: () => void;
+  onPrevious?: () => void;
+  service?: ServiceRef;
+}
+export interface WorkoutCardProps extends BaseProps {
+  /** "Run", "Ride", "Strength", "Golf" … */
+  type: string;
+  icon?: IconName;
+  date: Date | string | number;
+  /** Minutes. */
+  duration: number;
+  /** Kilometres. */
+  distance?: number;
+  calories?: number;
+  /** Average heart rate in bpm. */
+  heartRate?: number;
+  /** Minutes in heart-rate zones 1–5. */
+  zones?: number[];
+  service?: ServiceRef;
+}
+export interface CallItem {
+  id: string;
+  name: string;
+  number?: string;
+  direction: "incoming" | "outgoing" | "missed";
+  at: Date | string | number;
+  /** Seconds. */
+  duration?: number;
+  /** What the call was about (an assistant's summary). */
+  summary?: ReactNode;
+}
+export interface CallLogProps extends BaseProps {
+  calls: CallItem[];
+  /** "Now" for the day headings. */
+  now?: Date | string | number;
+  onCall?: (id: string) => void;
+  onOpen?: (id: string) => void;
+  /** Accessible name (default "Calls"). */
+  label?: string;
+}
+export interface ReservationCardProps extends BaseProps {
+  kind: "stay" | "flight" | "train" | "ride" | "order" | "event";
+  title: string;
+  /** "Hotel Atlantic · 2 nights", "LH 2024 · Seat 14A". */
+  subtitle?: ReactNode;
+  start: Date | string | number;
+  end?: Date | string | number;
+  /** Where: an address, airport codes, a restaurant. */
+  place?: ReactNode;
+  /** Booking or order number. */
+  code?: string;
+  status?: "confirmed" | "pending" | "cancelled" | "delayed" | "onTheWay" | "delivered";
+  /** Extra words for the status: "+25 min", "Arrives 19:40". */
+  statusText?: string;
+  service?: ServiceRef;
+  actions?: ReactNode;
+}
+export interface GolfHole {
+  par: number;
+  strokes?: number;
+  putts?: number;
+}
+export interface ScorecardProps extends BaseProps {
+  course: string;
+  date?: Date | string | number;
+  /** 9 or 18 holes. */
+  holes: GolfHole[];
+  /** Tee and course rating: "Yellow · CR 71.2 / SR 128". */
+  tee?: string;
+  service?: ServiceRef;
+}
+export interface Holding {
+  id: string;
+  name: string;
+  /** Ticker or ISIN. */
+  symbol?: string;
+  value: number;
+  /** Change in percent over `period`. */
+  change?: number;
+  /** Share of the portfolio in percent. */
+  weight?: number;
+}
+export interface HoldingsListProps extends BaseProps {
+  holdings: Holding[];
+  currency?: string;
+  /** The period of `change` ("today", "1 year"). */
+  period?: string;
+  onSelect?: (id: string) => void;
+  /** Accessible name (default "Holdings"). */
+  label?: string;
+}

package/src/context.ts

@@ -4,7 +4,14 @@
  * provider so a component that only needs its strings or formatters does not pull in theming.
  */
 import { createContext, useContext } from "react";
-import { LOCALE, formatDate, formatMoney, formatNumber, formatPercent } from "./format.js";
+import {
+  LOCALE,
+  formatDate,
+  formatMoney,
+  formatNumber,
+  formatPercent,
+  formatRelative,
+} from "./format.js";
 import {
   DEFAULT_STRINGS,
   SHARED_STRINGS,
@@ -87,6 +94,7 @@ export interface Formatters {
   formatMoney: (v: number, currency?: string | null, o?: Intl.NumberFormatOptions) => string;
   formatPercent: (v: number, o?: Intl.NumberFormatOptions) => string;
   formatDate: (input: Date | string | number, o?: Intl.DateTimeFormatOptions) => string;
+  formatRelative: (input: Date | string | number, now?: Date | string | number) => string;
 }
 
 const formatters = new Map<string, Formatters>();
@@ -100,6 +108,7 @@ export function formattersFor(locale: string): Formatters {
       formatMoney: (v, currency, o) => formatMoney(v, currency, o, locale),
       formatPercent: (v, o) => formatPercent(v, o, locale),
       formatDate: (input, o) => formatDate(input, o, locale),
+      formatRelative: (input, now) => formatRelative(input, now, locale),
     };
     formatters.set(locale, f);
   }

package/src/format.ts

@@ -56,6 +56,39 @@ export function formatDate(
   }
 }
 
+/**
+ * A moment relative to now, in words: "5 minutes ago", "in 2 hours", "yesterday". Picks the
+ * largest unit that fits; pass `now` so server and client render the same text.
+ */
+export function formatRelative(
+  input: Date | string | number,
+  now: Date | string | number = Date.now(),
+  locale?: string,
+): string {
+  const t = (input instanceof Date ? input : new Date(input)).getTime();
+  const n = (now instanceof Date ? now : new Date(now)).getTime();
+  const sec = Math.round((t - n) / 1000);
+  const abs = Math.abs(sec);
+  const steps: [Intl.RelativeTimeFormatUnit, number][] = [
+    ["second", 1],
+    ["minute", 60],
+    ["hour", 3600],
+    ["day", 86400],
+    ["week", 604800],
+    ["month", 2629800],
+    ["year", 31557600],
+  ];
+  let unit: Intl.RelativeTimeFormatUnit = "second";
+  let size = 1;
+  for (const [u, s] of steps) if (abs >= s) [unit, size] = [u, s];
+  try {
+    const rtf = new Intl.RelativeTimeFormat(locale || LOCALE, { numeric: "auto" });
+    return abs < 45 ? rtf.format(0, "second") : rtf.format(Math.round(sec / size), unit);
+  } catch {
+    return new Date(t).toLocaleString();
+  }
+}
+
 /** The group and decimal separators of a locale: `en-US` → `{ group: ",", decimal: "." }`. */
 export function numberSeparators(locale?: string): { group: string; decimal: string } {
   let group = ",",