@gogitcms/design-system 0.15.0-next.3

package/src/components/documentDrafts.ts

@@ -0,0 +1,213 @@
+// Unsaved edits, kept in the browser until the author saves them.
+//
+// The editor used to autosave every keystroke to the API, which meant every
+// half-finished sentence became a row in the database and, through the
+// exporter, a commit on the branch. Editing is now explicit: edits accumulate
+// here, the header says the document has unsaved changes, and Save is what
+// reaches the API and git.
+//
+// That makes this the only copy of work in progress, so it is written to
+// localStorage rather than sessionStorage: a closed tab, a crashed browser or a
+// reboot must not lose an afternoon's writing. The draft is offered back when
+// the document is reopened, and Discard is the way out.
+//
+// Not every host has localStorage — the design system also runs in the mobile
+// app, where `window` has no storage at all — so a missing store degrades to an
+// in-memory map: drafts still survive navigating between documents within the
+// session, which is the case that matters there, and nothing throws.
+
+/** One document's unsaved edits. */
+export type DocumentDraft = {
+  /** Schema version, so a future format change can ignore old drafts. */
+  v: 1;
+  /** The editor's value map, exactly as it edits it. */
+  values: Record<string, unknown>;
+  /** When it was last written, for the "unsaved since" affordance. */
+  at: number;
+};
+
+const PREFIX = "gitcms.draft.v1:";
+
+// The in-memory fallback, also the store under a browser that refuses
+// localStorage (Safari in private mode throws on write, not on access).
+const memory = new Map<string, string>();
+
+type Store = {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+  remove(key: string): void;
+  keys(): string[];
+};
+
+function store(): Store {
+  try {
+    const ls = typeof localStorage !== "undefined" ? localStorage : null;
+    if (ls) {
+      // Probed rather than assumed: private-mode Safari exposes localStorage and
+      // throws QuotaExceededError on the first write, and finding that out on
+      // the user's first keystroke is worse than finding it out now.
+      const probe = PREFIX + "probe";
+      ls.setItem(probe, "1");
+      ls.removeItem(probe);
+      return {
+        get: (k) => ls.getItem(k),
+        set: (k, v) => ls.setItem(k, v),
+        remove: (k) => ls.removeItem(k),
+        keys: () => Object.keys(ls),
+      };
+    }
+  } catch {
+    /* fall through to memory */
+  }
+  return {
+    get: (k) => memory.get(k) ?? null,
+    set: (k, v) => {
+      memory.set(k, v);
+    },
+    remove: (k) => {
+      memory.delete(k);
+    },
+    keys: () => [...memory.keys()],
+  };
+}
+
+// --- change notification ----------------------------------------------------
+//
+// The list marks documents that have drafts and counts them in its header, so
+// it has to re-render when one is written, saved or discarded — including from
+// another tab, where the same author may be editing the same repository.
+//
+// The cached id set is what makes this usable from a render: `hasDraft` is
+// called once per visible row, and re-reading localStorage on every one of them
+// would put a synchronous storage scan in the middle of scrolling.
+
+const listeners = new Set<() => void>();
+let cache: Set<string> | null = null;
+let storageBound = false;
+
+function invalidate() {
+  cache = null;
+  for (const l of listeners) l();
+}
+
+function ids(): Set<string> {
+  if (!cache) {
+    cache = new Set(
+      store()
+        .keys()
+        .filter((k) => k.startsWith(PREFIX))
+        .map((k) => k.slice(PREFIX.length)),
+    );
+  }
+  return cache;
+}
+
+/**
+ * subscribeDrafts registers a callback for any change to the set of documents
+ * with unsaved edits. Returns the unsubscribe.
+ *
+ * Shaped for useSyncExternalStore, which is why the readers below return
+ * primitives: a boolean and a number are stable between renders without the
+ * caching dance a returned Set or array would need.
+ */
+export function subscribeDrafts(onChange: () => void): () => void {
+  listeners.add(onChange);
+  // A draft written in another tab is a real change to what this list should
+  // show. Bound once, lazily, so a host that never renders a list never adds a
+  // window listener.
+  if (!storageBound && typeof window !== "undefined" && typeof window.addEventListener === "function") {
+    storageBound = true;
+    window.addEventListener("storage", (e) => {
+      if (!e.key || e.key.startsWith(PREFIX)) invalidate();
+    });
+  }
+  return () => {
+    listeners.delete(onChange);
+  };
+}
+
+/**
+ * refreshDrafts re-reads the store and notifies subscribers.
+ *
+ * The cache above assumes every write to these keys goes through this module,
+ * which holds within a tab — except when something clears storage wholesale
+ * (a host signing the user out, a test between cases). Those callers say so
+ * here rather than leaving the list showing badges for drafts that no longer
+ * exist. Cross-tab changes need no call: the storage event covers them.
+ */
+export function refreshDrafts(): void {
+  invalidate();
+}
+
+/** hasDraft reports whether a document has unsaved edits. */
+export function hasDraft(documentId: string): boolean {
+  return ids().has(documentId);
+}
+
+/** draftCount is how many documents have unsaved edits. */
+export function draftCount(): number {
+  return ids().size;
+}
+
+/**
+ * readDraft returns the stored draft for a document, or null.
+ *
+ * Anything unparseable or from another version is treated as absent and
+ * removed: a draft is a convenience, and refusing to open a document because
+ * its cached copy is malformed would be the worst possible trade.
+ */
+export function readDraft(documentId: string): DocumentDraft | null {
+  const s = store();
+  const key = PREFIX + documentId;
+  const raw = s.get(key);
+  if (!raw) return null;
+  try {
+    const parsed = JSON.parse(raw) as DocumentDraft;
+    if (parsed?.v !== 1 || typeof parsed.values !== "object" || parsed.values === null) {
+      s.remove(key);
+      invalidate();
+      return null;
+    }
+    return parsed;
+  } catch {
+    s.remove(key);
+    invalidate();
+    return null;
+  }
+}
+
+/** writeDraft stores a document's unsaved values. */
+export function writeDraft(documentId: string, values: Record<string, unknown>): void {
+  const draft: DocumentDraft = { v: 1, values, at: Date.now() };
+  const isNew = !ids().has(documentId);
+  try {
+    store().set(PREFIX + documentId, JSON.stringify(draft));
+    // Only the set of *which* documents have drafts is observable, so a
+    // rewrite of one that is already marked notifies nobody — that is every
+    // keystroke after the first.
+    if (isNew) invalidate();
+  } catch {
+    // Out of quota, or a value that will not serialize. The edit is still in
+    // component state and still savable; only the crash-safety copy is lost, so
+    // this must not interrupt typing.
+  }
+}
+
+/** clearDraft forgets a document's unsaved values — after a save, or a discard. */
+export function clearDraft(documentId: string): void {
+  try {
+    store().remove(PREFIX + documentId);
+    invalidate();
+  } catch {
+    /* nothing to do: a draft that cannot be removed is still only a cache */
+  }
+}
+
+/** draftIds lists every document with unsaved edits, for a global indicator. */
+export function draftIds(): string[] {
+  try {
+    return [...ids()];
+  } catch {
+    return [];
+  }
+}

package/src/components/layout.tsx

@@ -0,0 +1,284 @@
+import React from "react";
+import { View, ScrollView, StyleProp, ViewStyle } from "react-native";
+import { useTheme, useThemeMode, ThemeScope } from "../ThemeProvider";
+import { darkTheme } from "../theme";
+import { Text } from "./Text";
+import { IconButton } from "./Button";
+
+/** Full-height page background wrapper (used by simple screens like login). */
+export function Screen({
+  children,
+  center,
+  padded = true,
+  testID,
+  style,
+}: {
+  children: React.ReactNode;
+  center?: boolean;
+  padded?: boolean;
+  testID?: string;
+  style?: StyleProp<ViewStyle>;
+}) {
+  const t = useTheme();
+  return (
+    <View
+      testID={testID}
+      style={[
+        {
+          flex: 1,
+          backgroundColor: t.color.surfacePage,
+          padding: padded ? t.space(6) : 0,
+          justifyContent: center ? "center" : "flex-start",
+          gap: t.space(3),
+        },
+        style,
+      ]}
+    >
+      {children}
+    </View>
+  );
+}
+
+/** Horizontal top bar with left / center / right slots. */
+export function TopBar({
+  left,
+  center,
+  right,
+}: {
+  left?: React.ReactNode;
+  center?: React.ReactNode;
+  right?: React.ReactNode;
+}) {
+  const t = useTheme();
+  return (
+    <View
+      style={{
+        height: t.layout.topbar,
+        flexDirection: "row",
+        alignItems: "center",
+        paddingHorizontal: t.space(3),
+        gap: t.space(3),
+        borderBottomWidth: 1,
+        // Hairline appropriate to the dark chrome in both modes.
+        borderBottomColor: darkTheme.color.borderDefault,
+        // Permanent dark bar: near-black in light mode, charcoal in dark.
+        backgroundColor: t.color.surfaceTopBar,
+        // Establish a stacking context above the content panes so top-bar
+        // overlays (e.g. the notification menu) render on top of them.
+        position: "relative",
+        zIndex: 10,
+      }}
+    >
+      {/* The bar's inline contents render against the dark palette so text and
+          icons stay legible on the dark chrome, in both app themes. Overlays
+          that open from here (e.g. the notification menu) restore the page
+          theme themselves. */}
+      <ThemeScope theme={darkTheme}>
+        {/* The center slot is positioned against the BAR, not laid out between
+            its neighbours. As a flex sibling it would center in whatever space
+            the left and right slots left over — and those are never equal
+            widths (the workspace tag plus branch name is far wider than the
+            icon cluster), so it would sit visibly off-center. Absolute
+            positioning makes it centered on screen, which is the only centering
+            anyone can actually see.
+
+            Rendered first so the left/right slots paint above it: menus open
+            from those (branch, notifications) and must not fall behind it.
+
+            The overlay spans the whole bar, so it must not swallow clicks meant
+            for the slots underneath — hence `pointerEvents: "none"` here and
+            "auto" on the inner wrapper, which is the only combination that
+            actually works. React Native's `box-none` would express this in one
+            place, but react-native-web emits it verbatim as
+            `pointer-events: box-none`, which is not a valid CSS value: browsers
+            drop the declaration, the overlay falls back to `auto`, and the
+            branch menu, bell and sign-out all go dead. */}
+        {center ? (
+          <View
+            style={{
+              position: "absolute",
+              left: 0, right: 0, top: 0, bottom: 0,
+              flexDirection: "row",
+              alignItems: "center",
+              justifyContent: "center",
+              pointerEvents: "none",
+            }}
+          >
+            <View style={{ pointerEvents: "auto" }}>{center}</View>
+          </View>
+        ) : null}
+        <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(2) }}>{left}</View>
+        {/* Pushes the right slot to the trailing edge now that nothing between
+            them is flexing. */}
+        <View style={{ flex: 1 }} />
+        <View style={{ flexDirection: "row", alignItems: "center", gap: t.space(1) }}>{right}</View>
+      </ThemeScope>
+    </View>
+  );
+}
+
+/**
+ * A vertical column in the desktop multi-pane layout. Fixed `width` for
+ * sidebars/lists, or `flex` for the main content pane.
+ */
+export function Pane({
+  children,
+  width,
+  flex,
+  header,
+  borderRight = true,
+  scroll = true,
+  testID,
+  dataSet,
+}: {
+  children: React.ReactNode;
+  width?: number;
+  flex?: number;
+  header?: React.ReactNode;
+  borderRight?: boolean;
+  scroll?: boolean;
+  testID?: string;
+  // react-native-web maps this to data-* attributes on the pane's root element.
+  dataSet?: Record<string, string | number>;
+}) {
+  const t = useTheme();
+  // minHeight:0 lets the ScrollView shrink within the pane instead of growing
+  // it — so the body scrolls and the header (a sibling above it) stays put.
+  const body = scroll ? (
+    <ScrollView style={{ flex: 1, minHeight: 0 }} contentContainerStyle={{ paddingVertical: t.space(2) }}>
+      {children}
+    </ScrollView>
+  ) : (
+    <View style={{ flex: 1, minHeight: 0 }}>{children}</View>
+  );
+  return (
+    <View
+      testID={testID}
+      // @ts-expect-error react-native-web accepts dataSet -> data-* attributes
+      dataSet={dataSet}
+      style={{
+        width,
+        flex: width ? undefined : flex ?? 1,
+        minHeight: 0,
+        overflow: "hidden",
+        borderRightWidth: borderRight ? 1 : 0,
+        borderRightColor: t.color.borderSubtle,
+        backgroundColor: t.color.surfacePage,
+      }}
+    >
+      {header ? (
+        <View
+          style={{
+            height: t.layout.topbar,
+            paddingHorizontal: t.space(4),
+            flexDirection: "row",
+            alignItems: "center",
+            gap: t.space(2),
+            borderBottomWidth: 1,
+            borderBottomColor: t.color.borderSubtle,
+          }}
+        >
+          {header}
+        </View>
+      ) : null}
+      {body}
+    </View>
+  );
+}
+
+/** Desktop shell: a top bar over a horizontal row of panes. */
+export function AppShell({
+  topBar,
+  banner,
+  children,
+  testID,
+}: {
+  topBar?: React.ReactNode;
+  // Optional full-width strip below the top bar (e.g. a read-only notice).
+  banner?: React.ReactNode;
+  children: React.ReactNode;
+  testID?: string;
+}) {
+  const t = useTheme();
+  return (
+    <View testID={testID} style={{ flex: 1, backgroundColor: t.color.surfacePage }}>
+      {topBar}
+      {banner}
+      <View style={{ flex: 1, minHeight: 0, flexDirection: "row" }}>{children}</View>
+    </View>
+  );
+}
+
+/**
+ * Mobile drill-down screen: a compact header row, an optional large title, and
+ * a scrolling body — matching the native mobile layout.
+ */
+export function MobileScreen({
+  header,
+  title,
+  banner,
+  overlay,
+  children,
+  testID,
+  // Set false when the children own their own scrolling (e.g. a FlatList) so a
+  // VirtualizedList isn't nested inside this ScrollView.
+  scroll = true,
+}: {
+  header?: React.ReactNode;
+  title?: string;
+  // Full-width strip below the header (e.g. a read-only notice).
+  banner?: React.ReactNode;
+  // Absolutely-positioned overlay covering the whole screen (e.g. a modal),
+  // rendered outside the scroll area so it never scrolls with the body.
+  overlay?: React.ReactNode;
+  children: React.ReactNode;
+  testID?: string;
+  scroll?: boolean;
+}) {
+  const t = useTheme();
+  return (
+    <View testID={testID} style={{ flex: 1, backgroundColor: t.color.surfacePage }}>
+      {header ? (
+        <View
+          style={{
+            paddingHorizontal: t.space(4),
+            paddingTop: t.space(3),
+            flexDirection: "row",
+            alignItems: "center",
+            gap: t.space(3),
+          }}
+        >
+          {header}
+        </View>
+      ) : null}
+      {title ? (
+        <View style={{ paddingHorizontal: t.space(4), paddingTop: t.space(3), paddingBottom: t.space(3) }}>
+          <Text variant="h1" weight="bold" style={{ fontSize: 32, lineHeight: 38 }}>
+            {title}
+          </Text>
+        </View>
+      ) : null}
+      {banner}
+      {scroll ? (
+        <ScrollView style={{ flex: 1 }}>{children}</ScrollView>
+      ) : (
+        <View style={{ flex: 1, minHeight: 0 }}>{children}</View>
+      )}
+      {overlay}
+    </View>
+  );
+}
+
+/** Sun/moon button wired to the theme provider. */
+export function ThemeToggle({ size = "md" }: { size?: "sm" | "md" | "lg" }) {
+  const { mode, toggleMode } = useThemeMode();
+  return (
+    <IconButton
+      name={mode === "dark" ? "sun" : "moon"}
+      onPress={toggleMode}
+      size={size}
+      label={mode === "dark" ? "Switch to light theme" : "Switch to dark theme"}
+      testID="theme-toggle"
+    />
+  );
+}

package/src/components/primitives.tsx

@@ -0,0 +1,143 @@
+import React from "react";
+import { View, StyleProp, ViewStyle } from "react-native";
+import { useTheme } from "../ThemeProvider";
+import { Text } from "./Text";
+
+/** Bordered surface card — defined by a hairline border, never a shadow. */
+export function Card({
+  children,
+  padding = 4,
+  style,
+  testID,
+}: {
+  children: React.ReactNode;
+  padding?: number;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}) {
+  const t = useTheme();
+  return (
+    <View
+      testID={testID}
+      style={[
+        {
+          backgroundColor: t.color.surfaceRaised,
+          borderWidth: 1,
+          borderColor: t.color.borderDefault,
+          borderRadius: t.radius.md,
+          padding: t.space(padding),
+        },
+        style,
+      ]}
+    >
+      {children}
+    </View>
+  );
+}
+
+export type BadgeTone = "neutral" | "add" | "del" | "strong";
+
+/** Small pill for counts and git status letters (M/A/U/R/D). */
+export function Badge({
+  label,
+  tone = "neutral",
+  mono = true,
+  testID,
+}: {
+  label: string;
+  tone?: BadgeTone;
+  mono?: boolean;
+  testID?: string;
+}) {
+  const t = useTheme();
+  const tones: Record<BadgeTone, { bg: string; fg: string; border: string }> = {
+    neutral: { bg: t.color.surfaceSunken, fg: t.color.textSecondary, border: t.color.borderSubtle },
+    add: { bg: t.color.diffAddBg, fg: t.color.diffAddFg, border: t.color.diffAddBg },
+    del: { bg: t.color.diffDelBg, fg: t.color.diffDelFg, border: t.color.diffDelBg },
+    strong: { bg: t.color.surfaceInverted, fg: t.color.textInverted, border: t.color.surfaceInverted },
+  };
+  const c = tones[tone];
+  return (
+    <View
+      testID={testID}
+      style={{
+        paddingHorizontal: t.space(1.5),
+        height: 18,
+        justifyContent: "center",
+        borderRadius: t.radius.sm,
+        backgroundColor: c.bg,
+        borderWidth: 1,
+        borderColor: c.border,
+      }}
+    >
+      <Text variant="monoSm" mono={mono} color={c.fg} weight="medium">
+        {label}
+      </Text>
+    </View>
+  );
+}
+
+/** Git diff stat: `+N` in add color, `-N` in del color. */
+export function DiffStat({ added, removed }: { added?: number; removed?: number }) {
+  const t = useTheme();
+  return (
+    <View style={{ flexDirection: "row", gap: t.space(1.5) }}>
+      {added != null && added > 0 ? (
+        <Text variant="monoSm" color={t.color.diffAddFg} weight="medium">{`+${added}`}</Text>
+      ) : null}
+      {removed != null && removed > 0 ? (
+        <Text variant="monoSm" color={t.color.diffDelFg} weight="medium">{`-${removed}`}</Text>
+      ) : null}
+    </View>
+  );
+}
+
+/** Square initials avatar. */
+export function Avatar({ initials, size = 28 }: { initials: string; size?: number }) {
+  const t = useTheme();
+  return (
+    <View
+      style={{
+        width: size,
+        height: size,
+        borderRadius: t.radius.sm,
+        borderWidth: 1,
+        borderColor: t.color.borderDefault,
+        backgroundColor: t.color.surfaceSunken,
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      <Text variant="monoSm" weight="semibold" color="secondary">
+        {initials}
+      </Text>
+    </View>
+  );
+}
+
+/** Hairline rule. */
+export function Divider({ vertical, style }: { vertical?: boolean; style?: StyleProp<ViewStyle> }) {
+  const t = useTheme();
+  return (
+    <View
+      style={[
+        vertical
+          ? { width: 1, alignSelf: "stretch", backgroundColor: t.color.borderSubtle }
+          : { height: 1, alignSelf: "stretch", backgroundColor: t.color.borderSubtle },
+        style,
+      ]}
+    />
+  );
+}
+
+/** Uppercase tracked mono micro-label used for nav section headers. */
+export function SectionLabel({ children, style }: { children: React.ReactNode; style?: StyleProp<ViewStyle> }) {
+  const t = useTheme();
+  return (
+    <View style={[{ paddingHorizontal: t.space(4), paddingVertical: t.space(2) }, style]}>
+      <Text variant="label" color="tertiary">
+        {children}
+      </Text>
+    </View>
+  );
+}

package/src/components/reorder.ts

@@ -0,0 +1,40 @@
+// Pure geometry/list helpers for the desktop ContentBrowser's resizable panes
+// and drag-to-reorder columns. Kept side-effect-free so they unit-test without a
+// DOM (the drag/resize gestures themselves are exercised in the browser).
+
+/** Clamp `n` into the inclusive [min, max] range. */
+export function clamp(n: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, n));
+}
+
+/**
+ * Reorder `ids` by moving `dragId` to `slot` — a landing position expressed in
+ * the ORIGINAL list's coordinates (0..ids.length). Because removing the dragged
+ * id shifts later positions left by one, a slot past the id's own index is
+ * decremented. Returns a new array; a no-op (unknown id) returns the input.
+ */
+export function reorder(ids: string[], dragId: string, slot: number): string[] {
+  const from = ids.indexOf(dragId);
+  if (from === -1) return ids;
+  const without = ids.filter((x) => x !== dragId);
+  const to = clamp(from < slot ? slot - 1 : slot, 0, without.length);
+  without.splice(to, 0, dragId);
+  return without;
+}
+
+/**
+ * The insertion slot (0..widths.length) for a pointer at content-x `x` over a
+ * horizontal row of columns with the given `widths`, laid out left-to-right. A
+ * column is "passed" once the pointer clears its midpoint, so dropping snaps to
+ * whichever gap the cursor is nearest.
+ */
+export function slotAtX(x: number, widths: number[]): number {
+  let left = 0;
+  let slot = 0;
+  for (const w of widths) {
+    if (x <= left + w / 2) break;
+    slot++;
+    left += w;
+  }
+  return slot;
+}