@anchrd/intel 0.59.0

package/ui/src/time/time.ts

@@ -0,0 +1,165 @@
+// The ONE place a timestamp becomes a readable sentence (#467).
+//
+// Every surface used to call `toLocaleString(locale)` for itself, which silently takes the DEVICE's
+// zone. Three things follow that are not true:
+//
+//   1. Whoever travels, or uses a device in another zone, reads different times for the same
+//      events. For a record of what happened that is where it stops being evidence.
+//   2. Nowhere does it say WHICH zone applies. A time without a zone is a number, not a statement —
+//      and it looks exactly like a real one.
+//   3. Two people looking at the same entry see different times and cannot refer to one in
+//      conversation.
+//
+// ⚠️ **The zone is a LENS for reading, never a change to the value.** What is stored and sent stays
+// UTC; this module only formats.
+//
+// ⚠️ The comment in `settings-dialog.tsx` is what this file answers: the timezone left with the
+// Agents (#388) because nothing read it, and "a preference that changes nothing on screen is worse
+// than none". This exists BEFORE the preference does, and that order is the whole of #467.
+
+export interface TimeZoneStore {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+const StorageKey = "intel.timezone";
+
+// "This device's zone" as an explicit choice rather than an empty field: an empty field would look
+// as if nothing were set, and invite somebody to set what already holds.
+export const DeviceZone = "device";
+export type ZoneChoice = string;
+
+// ⚠️ Falling back to UTC rather than throwing: in an environment without Intl a time in UTC is
+// still a time, while a thrown exception is an empty screen.
+export function deviceZone(): string {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC";
+  } catch {
+    return "UTC";
+  }
+}
+
+// The stored value comes out of `localStorage` and may have been edited by hand, written by an older
+// build, or name a zone this runtime does not know.
+export function isKnownZone(zone: string): boolean {
+  if (zone === DeviceZone) return true;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readZoneChoice(store?: TimeZoneStore): ZoneChoice {
+  try {
+    const stored = store?.getItem(StorageKey);
+    return stored && isKnownZone(stored) ? stored : DeviceZone;
+  } catch {
+    return DeviceZone;
+  }
+}
+
+export function rememberZoneChoice(choice: ZoneChoice, store?: TimeZoneStore): void {
+  try {
+    store?.setItem(StorageKey, choice);
+  } catch {
+    // Without storage the choice holds for this session. Less than the reader wanted, more than an
+    // error they cannot switch off.
+  }
+}
+
+export function resolveZone(choice: ZoneChoice): string {
+  return choice === DeviceZone || !isKnownZone(choice) ? deviceZone() : choice;
+}
+
+/**
+ * A timestamp as a readable sentence — WITH its zone.
+ *
+ * ⚠️ The abbreviation is not decoration: a shifted time without one is precisely the silent
+ * misstatement this ticket is written against. And it comes from the runtime rather than from a
+ * string in the code — the runtime knows daylight saving, an appended label would be wrong for half
+ * the year.
+ *
+ * ⚠️ Individual components rather than `dateStyle`/`timeStyle`: Intl refuses the two style
+ * shorthands TOGETHER with `timeZoneName` and throws `Invalid option` — inside a table cell that
+ * takes the whole list with it. Found the hard way in `anchrd/gate#286`, where it read as "the row
+ * is missing" rather than as a formatting error.
+ */
+export function formatDateTime(value: string, locale: string, choice: ZoneChoice): string {
+  const date = new Date(value);
+  // An unreadable timestamp travels through rather than rendering as "Invalid Date": the raw value
+  // at least says what stood there.
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleString(locale, {
+    timeZone: resolveZone(choice),
+    year: "numeric",
+    month: "short",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    timeZoneName: "short",
+  });
+}
+
+/**
+ * The date alone, for the column that only ever showed one (the folder table's "Changed").
+ *
+ * ⚠️ It still resolves through the chosen zone, and that is the point rather than a detail: near
+ * midnight a date is exactly the value that differs between two zones, and a bare date carries no
+ * abbreviation to warn anybody.
+ */
+export function formatDate(value: string, locale: string, choice: ZoneChoice): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleDateString(locale, { timeZone: resolveZone(choice) });
+}
+
+const Minute = 60_000;
+const Hour = 60 * Minute;
+const Day = 24 * Hour;
+const Month = 30 * Day;
+
+/** A compact list value. Thirty days is the explicit month boundary; calendar labels stay in the tooltip. */
+export function formatRelativeTime(
+  value: string,
+  locale: string,
+  choice: ZoneChoice,
+  now: number,
+): string {
+  const date = new Date(value);
+  const target = date.getTime();
+  if (Number.isNaN(target)) return value;
+  const difference = target - now;
+  const distance = Math.abs(difference);
+  const relative = new Intl.RelativeTimeFormat(locale, { numeric: "auto", style: "short" });
+  if (distance < Minute) return relative.format(0, "second");
+  if (distance < Hour) return relative.format(Math.trunc(difference / Minute), "minute");
+  if (distance < Day) return relative.format(Math.trunc(difference / Hour), "hour");
+  if (distance < Month) return relative.format(Math.trunc(difference / Day), "day");
+  return formatDate(value, locale, choice);
+}
+
+// ⚠️ A short curated list rather than `Intl.supportedValuesOf("timeZone")` — that is over 400
+// entries, and a dropdown of 400 rows without a search is not a choice but an imposition. A zone
+// missing here is added once it has been missed three times; until then the device's zone is the
+// answer, and it is the right one for almost everybody. Ordered by offset, so the list reads like a
+// map.
+export const ZoneOptions: readonly string[] = [
+  "UTC",
+  "Europe/Lisbon",
+  "Europe/Berlin",
+  "Europe/Athens",
+  "Europe/Moscow",
+  "Asia/Dubai",
+  "Asia/Kolkata",
+  "Asia/Singapore",
+  "Asia/Tokyo",
+  "Australia/Sydney",
+  "Pacific/Auckland",
+  "America/Sao_Paulo",
+  "America/New_York",
+  "America/Chicago",
+  "America/Denver",
+  "America/Los_Angeles",
+];

package/ui/src/title-row/title-row.tsx

@@ -0,0 +1,185 @@
+import {
+  createContext,
+  type HTMLAttributes,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import { ResourceAccessSummary } from "@/access-summary/access-summary.tsx";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { cn } from "@/lib/utils";
+import { NodeDetails } from "@/node-details/node-details.tsx";
+import { ResourceMenu, type ResourceTarget } from "@/resource-menu/resource-menu.tsx";
+
+const TitleRowScrollContext = createContext<{
+  scrolled: boolean;
+  setScrolled(scrolled: boolean): void;
+} | null>(null);
+
+export function TitleRowFrame({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  const [scrolled, setScrolled] = useState(false);
+  const value = useMemo(() => ({ scrolled, setScrolled }), [scrolled]);
+  return (
+    <TitleRowScrollContext.Provider value={value}>
+      <div className={className} {...props} />
+    </TitleRowScrollContext.Provider>
+  );
+}
+
+export function TitleRowScrollArea({
+  className,
+  onScroll,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) {
+  const scroll = useContext(TitleRowScrollContext);
+  const setScrolled = scroll?.setScrolled;
+  useEffect(() => () => setScrolled?.(false), [setScrolled]);
+  return (
+    <div
+      className={className}
+      onScroll={(event) => {
+        scroll?.setScrolled(event.currentTarget.scrollTop > 0);
+        onScroll?.(event);
+      }}
+      {...props}
+    />
+  );
+}
+
+/**
+ * The one line an open thing gets: its name on the left, everything that acts on it on the right
+ * (#53).
+ *
+ * ⚠️ The order of the right-hand group belongs to this component, not to its callers. Whatever they
+ * pass as `children` is rendered before the menu and the menu is appended last, always — so a screen
+ * that grows a new button cannot push the three dots to the left, and there is no second place where
+ * the rule could be forgotten. That is the whole point: the menu holds rename, move, share and
+ * archive, and a position one has to look for is a position one stops using.
+ *
+ * The two slots are for what belongs to this thing but lives further down the tree, where its
+ * state is. `title-meta` is a quiet word beside the name (a table's row count); `title-actions` is a
+ * button in the group (saving a document, exporting a table). Both are filled through `ActionSlot`,
+ * and the one in the group sits before the menu for the same reason `children` do.
+ */
+export function TitleRow({
+  title,
+  crumbs,
+  target,
+  separated,
+  children,
+}: {
+  /**
+   * ⚠️ **Not drawn while `crumbs` is set** — the path names the thing then, and nothing falls back
+   * to this. It stays required all the same, so every caller has to state in one word what the row
+   * is about: the next reader of this call site should not have to follow a component two files
+   * away to find out.
+   */
+  title: string;
+  /**
+   * A path that stands in for the name.
+   *
+   * ⚠️ **It REPLACES the heading, it does not join it.** An open board card carries its name in the
+   * path already, and the same sentence twice above one another says nothing twice (#692). The row
+   * itself, its menu order and its slots stay exactly as they are: only what identifies the thing
+   * changes, because for a card the answer is "where it sits", not just "what it is called".
+   */
+  crumbs?: ReactNode;
+  /**
+   * What the three-dot menu acts on. ⚠️ **Absent means NO menu**, and that is a real state rather
+   * than an oversight: a card whose node has not arrived yet has nothing the menu could rename,
+   * move or archive, and pointing it at the container instead would archive the wrong thing without
+   * asking (#692).
+   */
+  target?: ResourceTarget;
+  /**
+   * A separator that does NOT wait for a scroll.
+   *
+   * ⚠️ For a surface where scrolling cannot happen, and that is the only case it is for (#634). The
+   * edge below this row is normally `scrolled`, set by `TitleRowScrollArea` — which is right where
+   * content moves under the row. The flow canvas does not scroll, it pans: nothing ever sets
+   * `scrolled`, so the row sat on the dark canvas with no edge at all. Do not pass this where the
+   * content does scroll; a permanent edge there would replace a signal with decoration.
+   */
+  separated?: boolean;
+  children?: ReactNode;
+}) {
+  const i18n = useI18n();
+  const scroll = useContext(TitleRowScrollContext);
+  const setScrolled = scroll?.setScrolled;
+  const targetId =
+    target === undefined ? undefined : target.type === "flow" ? target.flow.id : target.node.id;
+  useEffect(() => {
+    void targetId;
+    setScrolled?.(false);
+  }, [setScrolled, targetId]);
+  return (
+    <div
+      data-scrolled={scroll?.scrolled || undefined}
+      className={cn(
+        "relative z-10 flex shrink-0 justify-between gap-5 px-6 py-4 transition-shadow",
+        // ⚠️ Two alignments for two shapes (#724). A document's name can carry a description under
+        // it, so its block starts at the top and the menu lines up with the FIRST line. A path is
+        // always one line, and starting it at the top leaves it sitting a hair above the icons it
+        // shares the row with. Centred, the two read as one line, which is what they are.
+        crumbs === undefined ? "items-start" : "items-center",
+        (separated || scroll?.scrolled) && "shadow-[inset_0_-1px_0_var(--border)]",
+      )}
+    >
+      <div className="flex min-w-0 items-center gap-3">
+        <div className="min-w-0">
+          <div className="flex min-w-0 flex-wrap items-baseline gap-x-3">
+            {crumbs === undefined ? (
+              <h2 className="truncate text-lg font-semibold">{title}</h2>
+            ) : (
+              crumbs
+            )}
+            {/* ⚠️ **The one place the slash command is written out** (#775). Quiet, beside the name,
+                where somebody who has the document open can read what to type. Not in the sidebar —
+                240px cut the titles down to `Angebo…` to say this — and not in the menu entry, which
+                is one line above it and would be the same sentence twice.
+
+                ⚠️ It carries its own accessible name rather than standing as bare text: `/billing`
+                out of context is a path, and a reader who cannot see the layout has nothing telling
+                them it is a command. */}
+            {target?.type === "node" && target.node.promptName !== null ? (
+              <span className="truncate text-sm text-muted-foreground">
+                <span className="sr-only">
+                  {i18n.t("prompt.command", { name: target.node.promptName })}
+                </span>
+                <span aria-hidden="true">/{target.node.promptName}</span>
+              </span>
+            ) : null}
+            {target?.type === "node" && target.node.kind === "folder" ? (
+              <ResourceAccessSummary resourceId={target.node.id} ownerId={target.node.ownerId} />
+            ) : null}
+            {/* A flow carries its own grants since #530, so who reaches it is worth showing where
+                it stands — the same question the folder above already answers here. */}
+            {target?.type === "flow" ? (
+              <ResourceAccessSummary
+                kind="flow"
+                resourceId={target.flow.id}
+                ownerId={target.flow.ownerId}
+              />
+            ) : null}
+            <span data-slot="title-meta" className="text-sm text-muted-foreground" />
+          </div>
+          {/* ⚠️ **The description is no longer running text under the name** (#819). It sits in the
+              details field with the facts of its kind, where it can also be changed — a file had
+              such a field and nothing else did. No target means nothing to describe and nothing to
+              change: an open card whose node has not arrived yet is the case (#692). */}
+          {target === undefined ? null : <NodeDetails key={targetId} target={target} />}
+        </div>
+      </div>
+      {/* ⚠️ Document order is tab order here — nothing carries a `tabIndex`. The menu is therefore
+          reached last by the keyboard for the same reason it stands last on screen, and the two
+          cannot drift apart without someone rewriting this line. */}
+      <div className="flex shrink-0 items-center gap-2">
+        <div data-slot="title-actions" className="flex items-center gap-2" />
+        {children}
+        {target === undefined ? null : <ResourceMenu target={target} variant="title" />}
+      </div>
+    </div>
+  );
+}