@sole-ui/react 0.0.0-stage → 0.2.0

package/dist/lib/dates.d.ts

@@ -0,0 +1,62 @@
+/** A calendar date as `YYYY-MM-DD`, with no time zone. */
+export type DateOnly = string;
+/** An instant as an ISO 8601 string. */
+export type Timestamp = string;
+export declare const SYDNEY = "Australia/Sydney";
+export declare function isDateOnly(value: unknown): value is DateOnly;
+/** The calendar date at instant `at` in `tz`. */
+export declare function dateIn(at: Date | Timestamp, tz?: string): DateOnly;
+/** Today on the work clock (Sydney unless told otherwise). */
+export declare function todayDate(now: Date, tz?: string): DateOnly;
+export declare function addDays(date: DateOnly, days: number): DateOnly;
+/** Calendar months, clamped: 31 Aug plus 6 months is 28 Feb (29 in a leap year). */
+export declare function addMonths(date: DateOnly, months: number): DateOnly;
+/** Whole days from `from` to `to`; negative when `to` is earlier. */
+export declare function daysBetween(from: DateOnly, to: DateOnly): number;
+/** 0 for Monday to 6 for Sunday. */
+export declare function weekdayIndex(date: DateOnly): number;
+/** The work week containing `date`: Monday to Sunday. */
+export declare function weekOf(date: DateOnly): {
+    start: DateOnly;
+    end: DateOnly;
+};
+export type DueTone = 'overdue' | 'today' | 'soon' | 'plain' | 'done';
+export interface DueChipModel {
+    tone: DueTone;
+    /** What the chip says: "9 Sep", "Today", "Tomorrow", "Fri", "9 Oct 2027". */
+    label: string;
+    /** For screen readers, e.g. "Overdue, due 9 Sep". */
+    ariaLabel: string;
+    /** The full date, for the tooltip. */
+    title: string;
+}
+/**
+ * The due-date chip (brand-and-ux 5.10). `done` is true for completed and cancelled
+ * items: their date is a plain fact and is never red.
+ */
+export declare function dueChip(due: DateOnly, today: DateOnly, done?: boolean): DueChipModel;
+/** "9 Sep" in the current year, "9 Sep 2027" otherwise. Pass `today` to decide the year. */
+export declare function formatDate(date: DateOnly, today?: DateOnly, opts?: {
+    year?: boolean;
+}): string;
+/** "9 September 2026", or "Wednesday, 9 September 2026" with `weekday`. `year: false` drops the year. */
+export declare function formatLongDate(date: DateOnly, opts?: {
+    weekday?: boolean;
+    year?: boolean;
+}): string;
+/** "3:00 PM", "9:30 AM": no leading zero, always minutes, upper-case AM and PM. */
+export declare function formatTime(at: Date | Timestamp, tz?: string): string;
+/** A timestamp as a date: "9 Sep", or "9 Sep 2025" in another year. */
+export declare function formatTimestampDate(at: Date | Timestamp, now: Date, tz?: string): string;
+/**
+ * Relative time for the Inbox and comments only (brand-and-ux 5.19): "Just now",
+ * "5 min ago", "2 h ago" today; "Yesterday"; the weekday within the last week;
+ * then the date. Always pair it with the absolute time in a tooltip.
+ */
+export declare function formatRelative(at: Date | Timestamp, now: Date, tz?: string): string;
+/** "Today 3:12 PM", "Yesterday 3:12 PM", "Fri 3:12 PM" within a week, else "9 Sep, 3:12 PM". */
+export declare function formatDayTime(at: Date | Timestamp, now: Date, tz?: string): string;
+/** The full stamp for tooltips: "Tuesday, 29 September 2026, 3:12 PM". */
+export declare function formatFullTimestamp(at: Date | Timestamp, tz?: string): string;
+/** Home's greeting: before 12 is morning, before 6 PM is afternoon. */
+export declare function greeting(now: Date, tz?: string): 'Good morning' | 'Good afternoon' | 'Good evening';

package/dist/lib/dates.js

@@ -0,0 +1,182 @@
+import { TZDate } from '@date-fns/tz';
+// Every date rule in one place (brand-and-ux 5.10 and 5.19, behaviour-core 3.3, D15).
+//
+// Two clocks, on purpose:
+// - The WORK clock is Australia/Sydney, always. "Today", "overdue" and "this week"
+//   must mean the same thing for every colleague, whatever their own timezone is.
+// - DISPLAY of timestamps (a comment's time) uses the viewer's profile timezone,
+//   which defaults to Sydney too.
+//
+// Names of months and weekdays are written out here rather than taken from Intl:
+// current ICU prints "Sept" for en-AU, and the house format is "9 Sep".
+// Nothing reads the clock: every function that needs the moment takes `now` or `today`.
+// A screen gets them from SoleProvider (useNow, useToday).
+export const SYDNEY = 'Australia/Sydney';
+const MONTHS_SHORT = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const MONTHS_LONG = [
+    'January', 'February', 'March', 'April', 'May', 'June',
+    'July', 'August', 'September', 'October', 'November', 'December',
+];
+/** Index 0 is Monday, the first day of the work week. */
+const WEEKDAYS_SHORT = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+const WEEKDAYS_LONG = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
+const pad = (n) => String(n).padStart(2, '0');
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+export function isDateOnly(value) {
+    if (typeof value !== 'string')
+        return false;
+    const m = DATE_ONLY.exec(value);
+    if (!m)
+        return false;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const t = new Date(Date.UTC(y, mo - 1, d));
+    return t.getUTCFullYear() === y && t.getUTCMonth() === mo - 1 && t.getUTCDate() === d;
+}
+function ymd(date) {
+    const m = DATE_ONLY.exec(date);
+    if (!m)
+        throw new Error(`Not a calendar date: ${date}`);
+    return { y: Number(m[1]), m: Number(m[2]), d: Number(m[3]) };
+}
+function fromUtc(t) {
+    return `${t.getUTCFullYear()}-${pad(t.getUTCMonth() + 1)}-${pad(t.getUTCDate())}`;
+}
+function toUtc(date) {
+    const { y, m, d } = ymd(date);
+    return new Date(Date.UTC(y, m - 1, d));
+}
+/** The calendar date at instant `at` in `tz`. */
+export function dateIn(at, tz = SYDNEY) {
+    const t = typeof at === 'string' ? new Date(at) : at;
+    const z = new TZDate(t.getTime(), tz);
+    return `${z.getFullYear()}-${pad(z.getMonth() + 1)}-${pad(z.getDate())}`;
+}
+/** Today on the work clock (Sydney unless told otherwise). */
+export function todayDate(now, tz = SYDNEY) {
+    return dateIn(now, tz);
+}
+export function addDays(date, days) {
+    const t = toUtc(date);
+    t.setUTCDate(t.getUTCDate() + days);
+    return fromUtc(t);
+}
+/** Calendar months, clamped: 31 Aug plus 6 months is 28 Feb (29 in a leap year). */
+export function addMonths(date, months) {
+    const { y, m, d } = ymd(date);
+    const index = y * 12 + (m - 1) + months;
+    const ny = Math.floor(index / 12);
+    const nm = index - ny * 12; // 0 to 11
+    const last = new Date(Date.UTC(ny, nm + 1, 0)).getUTCDate();
+    return fromUtc(new Date(Date.UTC(ny, nm, Math.min(d, last))));
+}
+/** Whole days from `from` to `to`; negative when `to` is earlier. */
+export function daysBetween(from, to) {
+    return Math.round((toUtc(to).getTime() - toUtc(from).getTime()) / 86_400_000);
+}
+/** 0 for Monday to 6 for Sunday. */
+export function weekdayIndex(date) {
+    return (toUtc(date).getUTCDay() + 6) % 7;
+}
+/** The work week containing `date`: Monday to Sunday. */
+export function weekOf(date) {
+    const start = addDays(date, -weekdayIndex(date));
+    return { start, end: addDays(start, 6) };
+}
+/**
+ * The due-date chip (brand-and-ux 5.10). `done` is true for completed and cancelled
+ * items: their date is a plain fact and is never red.
+ */
+export function dueChip(due, today, done = false) {
+    const title = formatLongDate(due, { weekday: true });
+    const short = formatDate(due, today);
+    if (done)
+        return { tone: 'done', label: short, ariaLabel: `Due ${short}`, title };
+    if (due < today)
+        return { tone: 'overdue', label: short, ariaLabel: `Overdue, due ${short}`, title };
+    if (due === today)
+        return { tone: 'today', label: 'Today', ariaLabel: 'Due today', title };
+    if (due === addDays(today, 1))
+        return { tone: 'soon', label: 'Tomorrow', ariaLabel: 'Due tomorrow', title };
+    if (due <= weekOf(today).end) {
+        const day = WEEKDAYS_SHORT[weekdayIndex(due)];
+        return { tone: 'soon', label: day, ariaLabel: `Due ${WEEKDAYS_LONG[weekdayIndex(due)]}`, title };
+    }
+    return { tone: 'plain', label: short, ariaLabel: `Due ${short}`, title };
+}
+// ---------------------------------------------------------------- formatting
+/** "9 Sep" in the current year, "9 Sep 2027" otherwise. Pass `today` to decide the year. */
+export function formatDate(date, today, opts = {}) {
+    const { y, m, d } = ymd(date);
+    const withYear = opts.year ?? (today ? ymd(today).y !== y : true);
+    return withYear ? `${d} ${MONTHS_SHORT[m - 1]} ${y}` : `${d} ${MONTHS_SHORT[m - 1]}`;
+}
+/** "9 September 2026", or "Wednesday, 9 September 2026" with `weekday`. `year: false` drops the year. */
+export function formatLongDate(date, opts = {}) {
+    const { y, m, d } = ymd(date);
+    const core = opts.year === false ? `${d} ${MONTHS_LONG[m - 1]}` : `${d} ${MONTHS_LONG[m - 1]} ${y}`;
+    return opts.weekday ? `${WEEKDAYS_LONG[weekdayIndex(date)]}, ${core}` : core;
+}
+/** "3:00 PM", "9:30 AM": no leading zero, always minutes, upper-case AM and PM. */
+export function formatTime(at, tz = SYDNEY) {
+    const t = typeof at === 'string' ? new Date(at) : at;
+    const z = new TZDate(t.getTime(), tz);
+    const h = z.getHours();
+    return `${h % 12 || 12}:${pad(z.getMinutes())} ${h < 12 ? 'AM' : 'PM'}`;
+}
+/** A timestamp as a date: "9 Sep", or "9 Sep 2025" in another year. */
+export function formatTimestampDate(at, now, tz = SYDNEY) {
+    return formatDate(dateIn(at, tz), dateIn(now, tz));
+}
+/**
+ * Relative time for the Inbox and comments only (brand-and-ux 5.19): "Just now",
+ * "5 min ago", "2 h ago" today; "Yesterday"; the weekday within the last week;
+ * then the date. Always pair it with the absolute time in a tooltip.
+ */
+export function formatRelative(at, now, tz = SYDNEY) {
+    const t = typeof at === 'string' ? new Date(at) : at;
+    const seconds = Math.floor((now.getTime() - t.getTime()) / 1000);
+    const day = dateIn(t, tz);
+    const current = dateIn(now, tz);
+    const ago = daysBetween(day, current);
+    if (seconds < 0 || ago < 0)
+        return formatDate(day, current);
+    if (ago === 0) {
+        if (seconds < 60)
+            return 'Just now';
+        if (seconds < 3600)
+            return `${Math.floor(seconds / 60)} min ago`;
+        return `${Math.floor(seconds / 3600)} h ago`;
+    }
+    if (ago === 1)
+        return 'Yesterday';
+    if (ago < 7)
+        return WEEKDAYS_LONG[weekdayIndex(day)];
+    return formatDate(day, current);
+}
+/** "Today 3:12 PM", "Yesterday 3:12 PM", "Fri 3:12 PM" within a week, else "9 Sep, 3:12 PM". */
+export function formatDayTime(at, now, tz = SYDNEY) {
+    const day = dateIn(at, tz);
+    const current = dateIn(now, tz);
+    const ago = daysBetween(day, current);
+    const time = formatTime(at, tz);
+    if (ago === 0)
+        return `Today ${time}`;
+    if (ago === 1)
+        return `Yesterday ${time}`;
+    if (ago > 1 && ago < 7)
+        return `${WEEKDAYS_SHORT[weekdayIndex(day)]} ${time}`;
+    return `${formatDate(day, current)}, ${time}`;
+}
+/** The full stamp for tooltips: "Tuesday, 29 September 2026, 3:12 PM". */
+export function formatFullTimestamp(at, tz = SYDNEY) {
+    return `${formatLongDate(dateIn(at, tz), { weekday: true })}, ${formatTime(at, tz)}`;
+}
+/** Home's greeting: before 12 is morning, before 6 PM is afternoon. */
+export function greeting(now, tz = SYDNEY) {
+    const h = new TZDate(now.getTime(), tz).getHours();
+    if (h < 12)
+        return 'Good morning';
+    if (h < 18)
+        return 'Good afternoon';
+    return 'Good evening';
+}

package/dist/lib/hue.d.ts

@@ -0,0 +1,3 @@
+/** The twelve label hues. Each one is a `.hue-<name>` class in tokens.css. */
+export type Hue = 'slate' | 'indigo' | 'violet' | 'blue' | 'cyan' | 'teal' | 'green' | 'lime' | 'amber' | 'orange' | 'rose' | 'pink';
+export declare const HUES: readonly Hue[];

package/dist/lib/hue.js

@@ -0,0 +1 @@
+export const HUES = ['slate', 'indigo', 'violet', 'blue', 'cyan', 'teal', 'green', 'lime', 'amber', 'orange', 'rose', 'pink'];

package/dist/lib/person.d.ts

@@ -0,0 +1,16 @@
+/** The one neutral shape for a person. HQ, the CRM and the Dialer each map their own rows to it. */
+export interface SolePerson {
+    id: string;
+    name: string;
+    avatarUrl?: string | null;
+    isBot?: boolean;
+}
+/** What a part shows for someone who has left (brand-and-ux 5.12). */
+export declare const FORMER_MEMBER = "Former member";
+/**
+ * First letter of the first two words: "Ava Thompson" is AT. A name that is still an
+ * email local part is one word, so "ava.t" is A.
+ */
+export declare function initials(name: string): string;
+/** The name a part shows: the person's name, or "Former member" when there is no person. */
+export declare function personName(person: SolePerson | null | undefined): string;

package/dist/lib/person.js

@@ -0,0 +1,17 @@
+/** What a part shows for someone who has left (brand-and-ux 5.12). */
+export const FORMER_MEMBER = 'Former member';
+/**
+ * First letter of the first two words: "Ava Thompson" is AT. A name that is still an
+ * email local part is one word, so "ava.t" is A.
+ */
+export function initials(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    const letters = words.slice(0, 2).map((w) => [...w][0] ?? '');
+    return letters.join('').toUpperCase() || '?';
+}
+/** The name a part shows: the person's name, or "Former member" when there is no person. */
+export function personName(person) {
+    if (!person)
+        return FORMER_MEMBER;
+    return person.name.trim() || FORMER_MEMBER;
+}

package/dist/lib/platform.d.ts

@@ -0,0 +1,4 @@
+/** True on macOS and iOS, where the command key is Cmd rather than Ctrl. */
+export declare function isApple(): boolean;
+/** "Cmd" on Apple machines, "Ctrl" elsewhere. */
+export declare function modKeyName(): 'Cmd' | 'Ctrl';

package/dist/lib/platform.js

@@ -0,0 +1,12 @@
+/** True on macOS and iOS, where the command key is Cmd rather than Ctrl. */
+export function isApple() {
+    if (typeof navigator === 'undefined')
+        return false;
+    const data = navigator.userAgentData;
+    const platform = data?.platform || navigator.platform || navigator.userAgent;
+    return /mac|iphone|ipad|ipod/i.test(platform);
+}
+/** "Cmd" on Apple machines, "Ctrl" elsewhere. */
+export function modKeyName() {
+    return isApple() ? 'Cmd' : 'Ctrl';
+}

package/dist/lib/sole-provider.d.ts

@@ -0,0 +1,35 @@
+import type { AnchorHTMLAttributes, ComponentType, ReactNode, RefAttributes } from 'react';
+import type { DateOnly } from './dates.ts';
+import type { SolePerson } from './person.ts';
+export interface SoleLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'> {
+    href: string;
+}
+/** A router's link, adapted to take `href`: react-router's `Link`, Next's `Link`, or a plain anchor. */
+export type SoleLinkComponent = ComponentType<SoleLinkProps & RefAttributes<HTMLAnchorElement>>;
+export interface SoleProviderProps {
+    children: ReactNode;
+    /** The link every part uses for an in-app address. Defaults to a plain `<a>`. */
+    linkComponent?: SoleLinkComponent;
+    /** The work clock's time zone. Defaults to Australia/Sydney. */
+    timeZone?: string;
+    /** The app's clock. Defaults to the real one; a demo or a test pins it. */
+    now?: () => Date;
+    /** Where a person's name links to, or null for no link. Defaults to no link. */
+    personHref?: (person: SolePerson) => string | null;
+}
+interface SoleContextValue {
+    linkComponent: SoleLinkComponent;
+    timeZone: string;
+    now: () => Date;
+    personHref: (person: SolePerson) => string | null;
+}
+export declare function SoleProvider({ children, linkComponent, timeZone, now, personHref }: SoleProviderProps): import("react").JSX.Element;
+/** The provider's four values, or the defaults when there is no provider. */
+export declare function useSole(): SoleContextValue;
+/** A link to an address inside the app. An absolute `http` address is always a plain anchor. */
+export declare const SoleLink: import("react").ForwardRefExoticComponent<SoleLinkProps & RefAttributes<HTMLAnchorElement>>;
+/** The current time, refreshed every `intervalMs` (a minute by default). */
+export declare function useNow(intervalMs?: number): Date;
+/** Today on the work clock, rolling over at midnight. */
+export declare function useToday(): DateOnly;
+export {};

package/dist/lib/sole-provider.js

@@ -0,0 +1,52 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, forwardRef, useContext, useEffect, useMemo, useState } from 'react';
+import { Tooltip as TooltipPrimitive } from 'radix-ui';
+import { SYDNEY, todayDate } from './dates.js';
+const PlainLink = forwardRef(function PlainLink(props, ref) {
+    return _jsx("a", { ref: ref, ...props });
+});
+const defaults = {
+    linkComponent: PlainLink,
+    timeZone: SYDNEY,
+    now: () => new Date(),
+    personHref: () => null,
+};
+const SoleContext = createContext(defaults);
+export function SoleProvider({ children, linkComponent, timeZone, now, personHref }) {
+    const value = useMemo(() => ({
+        linkComponent: linkComponent ?? defaults.linkComponent,
+        timeZone: timeZone ?? defaults.timeZone,
+        now: now ?? defaults.now,
+        personHref: personHref ?? defaults.personHref,
+    }), [linkComponent, timeZone, now, personHref]);
+    // Radix tooltips need a provider above them. It lives here so a consumer wraps the app once.
+    return (_jsx(SoleContext.Provider, { value: value, children: _jsx(TooltipPrimitive.Provider, { delayDuration: 400, children: children }) }));
+}
+/** The provider's four values, or the defaults when there is no provider. */
+export function useSole() {
+    return useContext(SoleContext);
+}
+/** A link to an address inside the app. An absolute `http` address is always a plain anchor. */
+export const SoleLink = forwardRef(function SoleLink(props, ref) {
+    const { linkComponent: Link } = useSole();
+    if (/^https?:/i.test(props.href))
+        return _jsx(PlainLink, { ref: ref, ...props });
+    return _jsx(Link, { ref: ref, ...props });
+});
+/** The current time, refreshed every `intervalMs` (a minute by default). */
+export function useNow(intervalMs = 60_000) {
+    const { now } = useSole();
+    const [value, setValue] = useState(() => now());
+    useEffect(() => {
+        setValue(now());
+        const timer = setInterval(() => setValue(now()), intervalMs);
+        return () => clearInterval(timer);
+    }, [now, intervalMs]);
+    return value;
+}
+/** Today on the work clock, rolling over at midnight. */
+export function useToday() {
+    const { timeZone } = useSole();
+    return todayDate(useNow(), timeZone);
+}

package/dist/styles.css

@@ -0,0 +1,64 @@
+/* The Sole look for Tailwind CSS v4. In your stylesheet:
+
+     @import "tailwindcss";
+     @import "@sole-ui/react/styles.css";
+
+   The tokens, the Tailwind mapping and the text-micro utility live in tokens.css, which
+   is generated from packages/tokens. This file adds the font, the base layer and the
+   reduced-motion rule, as Sole HQ has them. */
+
+@import "tw-animate-css";
+@import "@fontsource-variable/inter";
+@import "./tokens.css";
+
+/* Light only (D31, owner 29 Sep): no dark theme and no theme switch. Nothing ever sets
+   a .dark class, so this keeps any `dark:` utility a shadcn component brings with it
+   from switching on under the system's prefers-color-scheme. The dark values wait in
+   hq/design/README.md for later. */
+@custom-variant dark (&:is(.dark *));
+
+/* ------------------------------------------------------------------ base */
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  html {
+    -webkit-text-size-adjust: 100%;
+    text-size-adjust: 100%;
+  }
+  body {
+    @apply bg-background text-foreground font-sans text-body antialiased;
+    font-feature-settings: "cv11", "ss01";
+  }
+  /* Keys, dates, times and counts line up (brand-and-ux 1.4). */
+  .tnum,
+  time,
+  kbd {
+    font-variant-numeric: tabular-nums;
+  }
+  :focus-visible {
+    outline: none;
+  }
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
+}
+
+/* Motion (5.6): colour changes 120ms, panels 200ms on the rise curve, no bounce, and
+   none of it for anyone who asked the system for less motion. */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* The consumer's Tailwind scans the package's own files for the classes the parts use, so
+   a fresh app needs only the two imports. In dist this resolves to dist/. */
+@source "./";