@twentyfirstmedia/ui-core 0.5.0 → 0.7.0

package/src/components/types.ts

@@ -1,4 +1,14 @@
-import type { ChangeEvent, CSSProperties, MouseEvent, ReactNode } from "react";
+import type {
+  ChangeEvent,
+  CSSProperties,
+  ElementType,
+  FocusEvent,
+  InputHTMLAttributes,
+  KeyboardEvent,
+  MouseEvent,
+  ReactNode,
+  Ref,
+} from "react";
 import type { IconName } from "../icons.js";
 import type { ToastOptions } from "../toast-store.js";
 import type { Surface } from "../provider.js";
@@ -137,9 +147,21 @@ export interface SearchFieldProps extends BaseProps {
   placeholder?: string;
   /** Accessible name (default: the placeholder, or "Search"). */
   label?: string;
+  /** The key hint, e.g. "⌘K" (hidden on touch screens). */
   shortcut?: string;
+  /** ⌘/Ctrl + the hint's last key (K for "⌘K") focuses the field, except while typing elsewhere. */
+  bindShortcut?: boolean;
   value?: string;
+  defaultValue?: string;
   onChange?: (e: ChangeEvent<HTMLInputElement>) => void;
+  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+  onFocus?: (e: FocusEvent<HTMLInputElement>) => void;
+  onBlur?: (e: FocusEvent<HTMLInputElement>) => void;
+  id?: string;
+  name?: string;
+  autoFocus?: boolean;
+  /** For a search with suggestions (combobox): role, aria-controls, aria-activedescendant … */
+  inputProps?: InputHTMLAttributes<HTMLInputElement>;
 }
 export interface CheckboxProps extends BaseProps {
   name?: string;
@@ -214,7 +236,10 @@ export interface PanelProps extends BaseProps {
   surface?: Surface;
 }
 export interface PageHeaderProps extends BaseProps {
-  crumbs?: string[];
+  /** A breadcrumb above the title (see `Breadcrumb`): labels, or items with `href`/`onClick`. */
+  crumbs?: (string | Crumb)[];
+  /** The element crumb links render as, e.g. Next.js `Link`. */
+  crumbLinkAs?: ElementType;
   title: string;
   subtitle?: string;
   actions?: ReactNode[];
@@ -225,7 +250,8 @@ export interface NavItem {
   count?: number;
 }
 export interface TopBarProps extends BaseProps {
-  brand?: string;
+  /** The product name, or a node (a logo mark with the name). */
+  brand?: ReactNode;
   tag?: string;
   items: NavItem[];
   active?: string;
@@ -245,6 +271,14 @@ export interface RailItem {
 export interface SideRailProps extends BaseProps {
   top?: RailItem[];
   bottom?: RailItem[];
+  /** Names next to the icons (controlled); every button has a tooltip while collapsed. */
+  expanded?: boolean;
+  defaultExpanded?: boolean;
+  onExpandedChange?: (expanded: boolean) => void;
+  /** A button at the foot that expands and collapses the rail. */
+  toggle?: boolean;
+  /** Accessible name of the rail (default "Tools"). */
+  label?: string;
 }
 export interface FloatingLayoutProps extends BaseProps {
   /** What the UI floats over, filling the layout: a map, a 3D canvas, a video, a photo. */
@@ -257,7 +291,23 @@ export interface FloatingLayoutProps extends BaseProps {
   end?: ReactNode;
   /** Bar along the bottom edge (dock, playback, a summary). */
   bottom?: ReactNode;
-  /** Height of the layout (default 640). Below 720px of width the slots stack: top, start, end, bottom. */
+  /** Controls of the background (zoom, compass, locate) in the free corner above the bottom bar. */
+  controls?: ReactNode;
+  /** Source notes of the background (map attribution), under `controls`, clear of every slot. */
+  attribution?: ReactNode;
+  /** Width of the start column (default 320px) and of the end column (default 340px). */
+  startWidth?: number | string;
+  endWidth?: number | string;
+  /**
+   * Below 720px of width the end slot becomes a bottom sheet over the background, with a handle
+   * that expands and collapses it (default true). `false` stacks it with the others.
+   */
+  endSheet?: boolean;
+  /**
+   * Height of the layout (default 640). Below 720px of width the slots stack: top, start, end,
+   * bottom. The layout sets `--floating-safe-top/-start/-end/-bottom` (px) to the space its
+   * slots take, so map libraries can keep their own controls clear of them.
+   */
   height?: number | string;
   /** Glass for every surface in the slots (default) or solid surfaces. */
   surface?: Surface;
@@ -304,6 +354,11 @@ export interface TableProps extends BaseProps {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- rows are app data
   rows: Record<string, any>[];
   animate?: boolean;
+  /**
+   * Cards instead of columns when the table's box is narrow (up to 600px): every row stacks its
+   * cells, each with its column label. Without it narrow tables scroll sideways.
+   */
+  stack?: boolean;
 }
 export interface ProgressProps extends BaseProps {
   value: number;
@@ -324,8 +379,21 @@ export interface EmptyStateProps extends BaseProps {
   tint?: Tint;
   action?: ReactNode;
 }
+/** A breadcrumb: a plain label, or one with an address or a handler. */
+export interface Crumb {
+  label: string;
+  href?: string;
+  onClick?: () => void;
+}
 export interface BreadcrumbProps extends BaseProps {
-  items: string[];
+  /** The trail; the last one is the current page. Items with `href` are links, with `onClick` buttons. */
+  items: (string | Crumb)[];
+  /** The element links render as (default `a`), e.g. Next.js `Link`. */
+  linkAs?: ElementType;
+  /** Makes every crumb but the last a button; receives its index. */
+  onNavigate?: (index: number) => void;
+  /** Accessible name of the navigation (default "Breadcrumb"). */
+  label?: string;
 }
 export interface PaginationProps extends BaseProps {
   /** Number of pages. */
@@ -339,10 +407,17 @@ export interface PaginationProps extends BaseProps {
   defaultPage?: number;
   /** A page was picked (previous, next or a number); receives the new 1-based page. */
   onChange?: (page: number) => void;
+  /** Link mode for server-rendered lists: the address of a page; pages become links. */
+  href?: (page: number) => string;
+  /** The element links render as (default `a`), e.g. Next.js `Link`. */
+  linkAs?: ElementType;
+  /** Accessible name of the navigation (default "Pagination"), e.g. "Search results pages". */
+  label?: string;
 }
 export interface AppShellProps extends BaseProps {
   active?: string;
-  brand?: string;
+  /** The product name, or a node (a logo mark with the name; collapsed sidebars show it whole). */
+  brand?: ReactNode;
   tag?: string;
   nav?: NavItem[];
   user?: { name: string; email?: string };
@@ -355,6 +430,19 @@ export interface AppShellProps extends BaseProps {
   dockItems?: DockProps["items"];
   railTop?: RailItem[];
   railBottom?: RailItem[];
+  /**
+   * `top` (default): navigation in the top bar, tools in the side rail. `sidebar`: a labelled
+   * sidebar on the frame, with groups, nesting and a drawer on phones.
+   */
+  navigation?: "top" | "sidebar";
+  /** With `navigation="sidebar"`: groups instead of the flat `nav` list. */
+  sidebarGroups?: SidebarGroup[];
+  /** With `navigation="sidebar"`: more sidebar props (collapsed, storageKey, shortcut, linkAs …). */
+  sidebar?: Partial<Omit<SidebarProps, "variant" | "groups">>;
+  /** With `navigation="sidebar"`: the workspace switcher at the top instead of the brand. */
+  workspaces?: WorkspaceSwitcherProps;
+  /** The account menu's entries (with `navigation="sidebar"` at the foot of the sidebar). */
+  userMenu?: (MenuItem | "-")[];
   children?: ReactNode;
 }
 export interface StaggerProps extends BaseProps {
@@ -372,6 +460,8 @@ export interface CountUpProps extends BaseProps {
   duration?: number;
   delay?: number;
   className?: string;
+  /** `false`: show the value without counting (it is always the value on the server). */
+  animate?: boolean;
 }
 export interface ListRowProps extends BaseProps {
   avatar?: string;
@@ -385,6 +475,18 @@ export interface ListRowProps extends BaseProps {
   unread?: boolean;
   active?: boolean;
   onClick?: () => void;
+  /** Makes the row a link (with `linkAs` for a router's link). */
+  href?: string;
+  linkAs?: ElementType;
+  /**
+   * Buttons of the row's own (rename, remove …), outside the clickable area so nothing interactive
+   * is nested. Without `onClick` and `href` the row is not interactive at all.
+   */
+  actions?: ReactNode;
+  /** Lines the title may take before it ends in an ellipsis (default: it wraps freely). */
+  titleLines?: number;
+  /** Lines the subtitle may take (default 1); badges and facts wrap within them. */
+  subtitleLines?: number;
 }
 export interface TimelineProps extends BaseProps {
   items: {
@@ -673,6 +775,14 @@ export interface TextFieldProps extends Omit<FormFieldProps, "children"> {
   inputMode?: "none" | "text" | "tel" | "url" | "email" | "numeric" | "decimal" | "search";
   onChange?: (e: ChangeEvent<HTMLInputElement>) => void;
   onBlur?: (e: ChangeEvent<HTMLInputElement>) => void;
+  onKeyDown?: (e: KeyboardEvent<HTMLInputElement>) => void;
+  /**
+   * An interactive control at the end of the field (an `IconButton`: clear, copy, locate …). Unlike
+   * `suffix` it can be clicked, and it stays when the field shows an error or success mark.
+   */
+  action?: ReactNode;
+  /** For `type="password"`: a button that shows and hides the password (default true). */
+  reveal?: boolean;
 }
 export interface RadioGroupProps extends BaseProps {
   label?: string;
@@ -766,10 +876,18 @@ export interface SliderProps extends BaseProps {
   marks?: boolean;
   hint?: string;
 }
+export interface OtpInputHandle {
+  /** Empties every cell and focuses the first. */
+  reset: () => void;
+}
 export interface OtpInputProps extends BaseProps {
   length?: number;
   onComplete?: (code: string) => void;
   error?: boolean;
+  /** Empties the cells when `error` turns on, ready for the next try (default true). */
+  clearOnError?: boolean;
+  /** `ref.current.reset()` empties the cells on demand. */
+  ref?: Ref<OtpInputHandle>;
   label?: string;
 }
 export interface UploadFile {
@@ -789,9 +907,10 @@ export interface FileDropProps extends BaseProps {
   /**
    * The person picked or dropped files: the real `File` objects, after `accept` and `multiple`.
    * Upload them yourself. To show progress, control `files` and set each `progress`; an
-   * uncontrolled list shows them with their size only.
+   * uncontrolled list shows them with their size only. Return `false` to list none of them, or
+   * the files to list (for example after checking their size).
    */
-  onFiles?: (files: File[]) => void;
+  onFiles?: (files: File[]) => void | boolean | File[];
   /** Dropped files that do not match `accept` (show an inline Alert). */
   onReject?: (files: File[]) => void;
   /** A listed file was removed or its upload cancelled. */
@@ -806,6 +925,10 @@ export interface FileDropProps extends BaseProps {
   /** Accepted types, as for `<input type="file">` ("image/*,.pdf"); also checked on drop. */
   accept?: string;
   multiple?: boolean;
+  /** No picking or dropping; the list stays visible. */
+  disabled?: boolean;
+  /** Takes part in a surrounding form under this name: the listed files are submitted with it. */
+  name?: string;
 }
 export interface TooltipProps extends BaseProps {
   label: ReactNode;
@@ -962,6 +1085,8 @@ export interface LegendProps extends BaseProps {
 /* ── Kit 3: AI chat & agents ── */
 export interface Source {
   title: string;
+  /** More about the source in a tooltip: dataset, publisher, date ("Stand") … */
+  detail?: ReactNode;
   icon?: IconName;
   url?: string;
   onClick?: () => void;
@@ -1175,6 +1300,11 @@ export interface CheckoutStepsProps extends BaseProps {
   steps?: string[];
   current?: number;
   onPick?: (i: number) => void;
+  /**
+   * Numbers only, with the label of the current step (screen readers still hear every label).
+   * Narrow containers (up to 560px) get this on their own.
+   */
+  compact?: boolean;
 }
 export interface OrderTimelineProps extends BaseProps {
   status: "Placed" | "Paid" | "Packed" | "Shipped" | "Delivered" | "Refunded" | "Cancelled";
@@ -1183,7 +1313,15 @@ export interface OrderTimelineProps extends BaseProps {
 export interface PlanCardProps extends BaseProps {
   name: string;
   text?: string;
-  price: number | null;
+  /**
+   * A number is formatted as money (0 = "Free", null = "Let's talk"); any other node is shown as
+   * it is, e.g. a placeholder ("—") or a price the app formatted itself.
+   */
+  price: number | null | ReactNode;
+  /** Before the price, e.g. "from". */
+  pricePrefix?: ReactNode;
+  /** Under the price: net or gross, billed yearly, VAT note … */
+  priceNote?: ReactNode;
   was?: number;
   per?: string;
   features?: string[];
@@ -1194,6 +1332,9 @@ export interface PlanCardProps extends BaseProps {
   /** Disable the button, e.g. while a checkout starts or when the plan cannot be picked. */
   disabled?: boolean;
   onPick?: () => void;
+  /** The action as a link (checkout or sign-up page), with `linkAs` for a router's link. */
+  href?: string;
+  linkAs?: ElementType;
 }
 
 /* ── Kit 3: system screens ── */
@@ -1885,6 +2026,8 @@ export interface TilePickerProps extends BaseProps {
   multiple?: boolean;
   min?: number;
   label?: string;
+  /** `list`: one compact row per option (small picture or icon beside the label), e.g. on phones. */
+  layout?: "grid" | "list";
 }
 export interface ColorFieldProps extends BaseProps {
   label?: ReactNode;
@@ -2134,6 +2277,8 @@ export interface WorkspaceSwitcherProps extends BaseProps {
   footer?: ReactNode;
   variant?: "frame";
   width?: number;
+  /** Only the workspace's mark, its name as the accessible name (a collapsed sidebar). */
+  compact?: boolean;
 }
 export interface ExportDialogProps extends BaseProps {
   open?: boolean;
@@ -2158,6 +2303,12 @@ export interface ExportDialogProps extends BaseProps {
 }
 export interface TwoFactorSetupProps extends BaseProps {
   qr?: ReactNode;
+  /** The otpauth:// link: the kit draws its QR code (instead of `qr`). */
+  qrValue?: string;
+  /** A "Trust this device" checkbox under the code field; a string replaces its label. */
+  trustDevice?: boolean | string;
+  /** The trust checkbox changed. */
+  onTrustChange?: (trusted: boolean) => void;
   secret: string;
   onVerify?: (code: string) => boolean | Promise<boolean>;
   codes?: string[];
@@ -2214,7 +2365,13 @@ export interface GalleryProps extends BaseProps {
   loading?: "lazy" | "eager";
   /** `referrerPolicy` of every image, e.g. `"no-referrer"` for photos from other hosts. */
   referrerPolicy?: ImageReferrerPolicy;
+  /** First image when uncontrolled. */
   start?: number;
+  /** The shown image (controlled, 0-based), with `onIndexChange`. */
+  index?: number;
+  onIndexChange?: (index: number) => void;
+  /** Accessible name of the gallery (default "Images"), e.g. the listing's title. */
+  label?: string;
   ratio?: string;
   thumbs?: boolean;
   fullscreen?: boolean;
@@ -2356,13 +2513,21 @@ export interface CookieConsentProps extends BaseProps {
   categories?: {
     id: string;
     label: string;
-    text?: string;
+    /** What the category covers; may hold a link to the details. */
+    text?: ReactNode;
     required?: boolean;
     default?: boolean;
   }[];
   onSave?: (choices: Record<string, boolean>) => void;
   open?: boolean;
   inline?: boolean;
+  /**
+   * "Only necessary" and "Accept all" with the same weight (both secondary buttons), as German
+   * data protection authorities expect on the first layer.
+   */
+  equalChoice?: boolean;
+  /** Id of the banner (its text is referenced by `aria-describedby`). */
+  id?: string;
 }
 export interface AnnouncementBarProps extends BaseProps {
   children: ReactNode;
@@ -2432,6 +2597,8 @@ export interface ToggleGroupProps extends BaseProps {
   /** Accessible name of the group. */
   label: string;
   size?: "sm" | "md";
+  /** Fills the width and shares it evenly; labels end in an ellipsis when space runs short. */
+  block?: boolean;
 }
 export interface ButtonGroupProps extends BaseProps {
   /** Accessible name of the group. */
@@ -2515,6 +2682,8 @@ export interface SelectMenuProps extends FieldProps, BaseProps {
   onChange?: (value: string) => void;
   placeholder?: string;
   disabled?: boolean;
+  /** `sm`: a compact trigger, e.g. a sort menu next to a heading. */
+  size?: "sm" | "md";
 }
 
 /* ── Navigation ── */
@@ -2551,31 +2720,91 @@ export interface NavigationMenuProps extends BaseProps {
 export interface SidebarItem {
   id?: string;
   label: string;
-  icon: IconName;
+  /** Required for pages; options in a filter group usually go without. */
+  icon?: IconName;
   count?: number;
-  /** One level of nested pages, shown when the item is open. */
+  /** A small marker instead of a number: `"dot"` for new activity, or a short word such as "New". */
+  badge?: string;
+  /** Renders the item as a link to this address (with `linkAs` for a router's link, e.g. Next.js `Link`). */
+  href?: string;
+  /** Opens `href` in a new tab and says so. */
+  external?: boolean;
+  disabled?: boolean;
+  /** A menu behind a "…" button on the item (rename, share, remove …). */
+  actions?: (MenuItem | "-")[];
+  /** One level of nested pages, shown when the item is open (as a flyout when the sidebar is collapsed). */
   items?: Omit<SidebarItem, "items">[];
+  /**
+   * Makes the item a filter option: a checkbox (or a radio in a group with `select: "single"`)
+   * with its label and `count`, instead of a page.
+   */
+  checked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
 }
 export interface SidebarGroup {
+  id?: string;
   label?: string;
-  items: SidebarItem[];
+  items?: SidebarItem[];
+  /** Any content instead of (or after) the items: a `RangeSlider`, `DateRangePicker`, chips … */
+  content?: ReactNode;
+  /** For filter options (items with `checked`): `single` makes them radios (one choice per group). */
+  select?: "multiple" | "single";
+  /** The label folds the group open and shut. */
+  collapsible?: boolean;
+  /** For a collapsible group: starts open (default true). */
+  defaultOpen?: boolean;
+  /** A small button next to the label, e.g. "+" to add a project. */
+  action?: { label: string; icon?: IconName; onClick?: () => void };
 }
 export interface SidebarProps extends BaseProps {
   groups: SidebarGroup[];
   /** Id (or label) of the current page. */
   current?: string;
   onPick?: (id: string) => void;
+  /**
+   * `floating` (default): a card with rounded corners and a shadow. `attached`: full height, flush
+   * with the edge of the screen, divided by a line. `shell`: on the dark frame of `AppShell`.
+   */
+  variant?: "floating" | "attached" | "shell";
   /** Icons only. */
   collapsed?: boolean;
   defaultCollapsed?: boolean;
   onCollapsedChange?: (collapsed: boolean) => void;
-  /** Top of the sidebar (brand, workspace switcher). */
-  header?: ReactNode;
-  /** Bottom of the sidebar (account, settings). */
-  footer?: ReactNode;
-  /** Accessible name of the navigation. */
+  /** Remember the collapsed state in the browser under this key. */
+  storageKey?: string;
+  /** ⌘B (Ctrl+B) collapses and expands the sidebar, except while typing in a field. */
+  shortcut?: boolean;
+  /** The element items with an `href` render as (default `a`), e.g. Next.js `Link`. */
+  linkAs?: ElementType;
+  /** On phones (up to 760px wide): whether the drawer is open (controlled). */
+  mobileOpen?: boolean;
+  onMobileOpenChange?: (open: boolean) => void;
+  /** Top of the sidebar (brand, `WorkspaceSwitcher`); a function gets the collapsed state. */
+  header?: ReactNode | ((state: { collapsed: boolean }) => ReactNode);
+  /** Bottom of the sidebar (`UserMenu`, settings); a function gets the collapsed state. */
+  footer?: ReactNode | ((state: { collapsed: boolean }) => ReactNode);
+  /**
+   * `nav` (default) for app navigation. `aside` for filters, settings or other tools beside the
+   * content: a complementary region instead of a navigation landmark.
+   */
+  as?: "nav" | "aside";
+  /** Offers the collapse button and the icons-only mode (default true; filters usually set false). */
+  collapsible?: boolean;
+  /** Accessible name of the navigation (or the aside). */
   label?: string;
 }
+export interface UserMenuProps extends BaseProps {
+  name: string;
+  email?: string;
+  /** Picture URL; initials otherwise. */
+  avatar?: string;
+  /** The menu: profile, settings, sign out … */
+  items?: (MenuItem | "-")[];
+  /** Only the avatar (a collapsed sidebar). */
+  compact?: boolean;
+  /** Where the menu opens (default `top`, for the foot of a sidebar). */
+  side?: "top" | "bottom";
+}
 
 /* ── ResizablePanels ── */
 export interface ResizablePanelsProps extends BaseProps {
@@ -2590,3 +2819,339 @@ export interface ResizablePanelsProps extends BaseProps {
   /** Accessible names of the panels, used for the resize handles. */
   labels?: string[];
 }
+
+/* ── QrCode ── */
+export interface QrCodeProps extends BaseProps {
+  /** The text to encode: an otpauth:// link, a URL … */
+  value: string;
+  /** Error correction: L, M (default), Q or H. */
+  level?: "L" | "M" | "Q" | "H";
+  /** Width and height (default: the width of its container). */
+  size?: number | string;
+  /** Light modules around the code (default 4, the standard quiet zone). */
+  quiet?: number;
+  /** Accessible name (default "QR code"). */
+  label?: string;
+}
+
+/* ── Life: wellbeing, health, goals, AI insights, consent ── */
+export interface Habit {
+  id: string;
+  label: string;
+  icon?: IconName;
+  tint?: Tint;
+  /** One entry per day, oldest first, today last: true done, false missed, null no data. */
+  days: (boolean | null)[];
+  /** Days in a row (shown as "12-day streak"). */
+  streak?: number;
+  /** A short target, e.g. "8 glasses" or "3× a week". */
+  goal?: string;
+}
+export interface HabitTrackerProps extends BaseProps {
+  habits: Habit[];
+  /** Labels of the day columns, oldest first (default: weekday initials ending today). */
+  dayLabels?: string[];
+  /** Today's box of a habit was toggled. */
+  onToggle?: (id: string, done: boolean) => void;
+  /** Accessible name of the list (default "Habits"). */
+  label?: string;
+}
+export type MoodLevel = 1 | 2 | 3 | 4 | 5;
+export interface MoodPickerProps extends BaseProps {
+  value?: MoodLevel | null;
+  defaultValue?: MoodLevel | null;
+  onChange?: (mood: MoodLevel) => void;
+  /** The question (default "How are you feeling?"). */
+  label?: ReactNode;
+  /** Words for the five levels, lowest first (default Awful, Low, Okay, Good, Great). */
+  levels?: [string, string, string, string, string];
+  /** Only the faces; the words stay as accessible names. */
+  compact?: boolean;
+}
+export interface VitalTileProps extends BaseProps {
+  /** `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
+  label: string;
+  value: number;
+  unit?: string;
+  icon?: IconName;
+  /** The healthy range [low, high]; the tile says whether the value is below, in or above it. */
+  normal?: [number, number];
+  /** The whole scale of the band [min, max] (default: the normal range with room on both sides). */
+  scale?: [number, number];
+  /** Recent values, oldest first, drawn as a sparkline. */
+  trend?: number[];
+  /** Under the value: when it was measured, the source … */
+  caption?: ReactNode;
+  /** Digits after the decimal point (default 0). */
+  digits?: number;
+}
+export interface ActivityRing {
+  label: string;
+  value: number;
+  goal: number;
+  unit?: string;
+  tint?: Tint;
+}
+export interface ActivityRingsProps extends BaseProps {
+  /** Outer ring first. */
+  rings: ActivityRing[];
+  /** Diameter of the rings (default 132). */
+  size?: number;
+  /** Hide the legend beside the rings. */
+  legend?: boolean;
+  /** Accessible name (default "Activity"). */
+  label?: string;
+}
+export type SleepStage = "awake" | "rem" | "light" | "deep";
+export interface SleepSegment {
+  stage: SleepStage;
+  start: Date | string | number;
+  end: Date | string | number;
+}
+export interface SleepChartProps extends BaseProps {
+  /** The night in order, from falling asleep to getting up. */
+  segments: SleepSegment[];
+  /** Accessible name (default "Sleep stages"). */
+  label?: string;
+  /** Hide the totals per stage under the chart. */
+  summary?: boolean;
+}
+export interface MedicationItem {
+  id: string;
+  name: string;
+  dose?: string;
+  /** When, as shown ("08:00", "With breakfast"). */
+  time: string;
+  /** Set by the app, which knows the clock: default "taken" when `taken`, else "due". */
+  status?: "taken" | "due" | "missed" | "upcoming";
+  taken?: boolean;
+  note?: string;
+  icon?: IconName;
+}
+export interface MedicationListProps extends BaseProps {
+  items: MedicationItem[];
+  /** "Mark as taken" was pressed. */
+  onTake?: (id: string) => void;
+  /** Accessible name (default "Medication"). */
+  label?: string;
+}
+export interface JournalEntryProps extends BaseProps {
+  /** `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
+  date: Date | string | number;
+  title?: string;
+  mood?: MoodLevel;
+  tags?: string[];
+  children?: ReactNode;
+  /** Buttons at the end (edit, share …). */
+  actions?: ReactNode;
+}
+export interface GoalCardProps extends BaseProps {
+  /** `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
+  title: string;
+  value: number;
+  target: number;
+  /** How to show value and target (default number). */
+  format?: "number" | "money" | "percent";
+  /** Unit after numbers ("km", "books"). */
+  unit?: string;
+  currency?: string;
+  due?: Date | string | number;
+  icon?: IconName;
+  tint?: Tint;
+  milestones?: { label: string; done?: boolean }[];
+  /** A note under the progress ("€250 a month keeps you on track"). */
+  note?: ReactNode;
+}
+export interface InsightCardProps extends BaseProps {
+  /** `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
+  title: string;
+  children?: ReactNode;
+  icon?: IconName;
+  tone?: "info" | "success" | "warning" | "highlight";
+  /** Above the title: area and time ("Money · 2 h ago"). */
+  meta?: ReactNode;
+  /** Where the insight comes from, as chips (like chat sources). */
+  sources?: Source[];
+  /** Why the assistant shows it; folded away behind "Why am I seeing this?". */
+  why?: ReactNode;
+  onAccept?: () => void;
+  acceptLabel?: string;
+  onSnooze?: () => void;
+  onDismiss?: () => void;
+}
+export interface ConsentScope {
+  id: string;
+  label: string;
+  description?: string;
+  granted: boolean;
+  /** Needed for the connection to work at all: shown, not switchable. */
+  required?: boolean;
+}
+export interface ConsentConnector {
+  id: string;
+  name: string;
+  icon?: IconName;
+  /** A logo instead of the icon. */
+  logo?: ReactNode;
+  /** What the assistant uses it for. */
+  purpose?: ReactNode;
+  scopes: ConsentScope[];
+  lastUsed?: Date | string | number;
+}
+export interface ConsentListProps extends BaseProps {
+  /** `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
+  connectors: ConsentConnector[];
+  onScopeChange?: (connectorId: string, scopeId: string, granted: boolean) => void;
+  onRevoke?: (connectorId: string) => void;
+  /** Accessible name (default "Data access"). */
+  label?: string;
+}
+
+/* ── Life: money, insurance, deadlines, documents ── */
+export interface BudgetCategory {
+  id: string;
+  label: string;
+  icon?: IconName;
+  tint?: Tint;
+  spent: number;
+  limit: number;
+}
+export interface BudgetListProps extends BaseProps {
+  categories: BudgetCategory[];
+  currency?: string;
+  /** A category was picked (to show its transactions). */
+  onSelect?: (id: string) => void;
+  /** Accessible name (default "Budgets"). */
+  label?: string;
+}
+export interface Subscription {
+  id: string;
+  name: string;
+  icon?: IconName;
+  /** A logo instead of the icon. */
+  logo?: ReactNode;
+  amount: number;
+  period: "week" | "month" | "year";
+  /** Next charge. */
+  next?: Date | string | number;
+  status?: "active" | "trial" | "cancelled";
+  category?: string;
+}
+export interface SubscriptionListProps extends BaseProps {
+  items: Subscription[];
+  currency?: string;
+  /** "Manage" on a subscription (cancel, change plan …). */
+  onManage?: (id: string) => void;
+  /** Hide the monthly and yearly totals. */
+  totals?: boolean;
+  /** Accessible name (default "Subscriptions"). */
+  label?: string;
+}
+export interface NetWorthCardProps extends BaseProps {
+  /** `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
+  assets: { label: string; value: number; icon?: IconName }[];
+  liabilities?: { label: string; value: number; icon?: IconName }[];
+  /** Net worth over time, oldest first. */
+  history?: number[];
+  /** Change over `changeLabel` (e.g. +1,240 "since October"). */
+  change?: number;
+  changeLabel?: string;
+  currency?: string;
+  title?: string;
+}
+export interface DeadlineItem {
+  id: string;
+  title: string;
+  /** What kind: "Contract", "ID card", "Tax" … */
+  kind?: string;
+  icon?: IconName;
+  date: Date | string | number;
+  amount?: number;
+  done?: boolean;
+  note?: string;
+}
+export interface DeadlineListProps extends BaseProps {
+  items: DeadlineItem[];
+  /** The day to count from (default: now). Set it for server rendering and stable output. */
+  today?: Date | string | number;
+  /** Days ahead that count as soon (default 14). */
+  soon?: number;
+  currency?: string;
+  onDone?: (id: string) => void;
+  /** Accessible name (default "Deadlines"). */
+  label?: string;
+}
+export interface PolicyCardProps extends BaseProps {
+  /** `"glass"`: translucent glass over a backdrop (`Ambient`, a photo, a map); `"solid"` opts out inside a glass `UIProvider`. */
+  surface?: Surface;
+  /** The kind of insurance: "Household contents", "Liability" … */
+  type: string;
+  insurer: string;
+  icon?: IconName;
+  tint?: Tint;
+  policyNumber?: string;
+  /** Show only the last four characters of the policy number. */
+  maskNumber?: boolean;
+  /** Sum insured: a number (money) or text ("unlimited"). */
+  coverage?: number | ReactNode;
+  premium?: { amount: number; period: "month" | "quarter" | "year" };
+  deductible?: number;
+  renews?: Date | string | number;
+  status?: "active" | "pending" | "expiring" | "lapsed";
+  currency?: string;
+  /** Buttons at the foot (documents, report a claim …). */
+  actions?: ReactNode;
+}
+export interface CoverageRow {
+  id: string;
+  risk: string;
+  status: "covered" | "partial" | "none";
+  note?: ReactNode;
+  /** Which policy covers it. */
+  policy?: string;
+}
+export interface CoverageMatrixProps extends BaseProps {
+  rows: CoverageRow[];
+  /** Accessible name and caption (default "Coverage"). */
+  label?: string;
+}
+export interface ClaimStep {
+  label: string;
+  date?: Date | string | number;
+  state: "done" | "current" | "todo" | "failed";
+  note?: ReactNode;
+}
+export interface ClaimTimelineProps extends BaseProps {
+  title: string;
+  /** Reference and insurer under the title. */
+  meta?: ReactNode;
+  amount?: number;
+  currency?: string;
+  steps: ClaimStep[];
+}
+export interface LifeDocument {
+  id: string;
+  title: string;
+  category?: string;
+  icon?: IconName;
+  holder?: string;
+  expires?: Date | string | number;
+  /** "PDF · 240 KB" */
+  meta?: string;
+}
+export interface DocumentListProps extends BaseProps {
+  documents: LifeDocument[];
+  /** The day to count expiry from (default: now). */
+  today?: Date | string | number;
+  /** Days ahead that count as expiring soon (default 60). */
+  soon?: number;
+  onOpen?: (id: string) => void;
+  /** Accessible name (default "Documents"). */
+  label?: string;
+}