@lotics/ui 1.9.0 → 1.10.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@lotics/ui",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
     "./colors": "./src/colors.ts",
     "./mime": "./src/mime.ts",
+    "./download": "./src/download.ts",
     "./file_badge": "./src/file_badge.tsx",
     "./file_thumbnail": "./src/file_thumbnail.tsx",
     "./file_gallery_modal": "./src/file_gallery_modal.tsx",
@@ -18,6 +19,7 @@
     "./trend_chip": "./src/trend_chip.tsx",
     "./section_card": "./src/section_card.tsx",
     "./kpi_card": "./src/kpi_card.tsx",
+    "./ring_gauge": "./src/ring_gauge.tsx",
     "./alert_row": "./src/alert_row.tsx",
     "./stacked_progress_bar": "./src/stacked_progress_bar.tsx",
     "./legend_item": "./src/legend_item.tsx",

package/src/download.ts

@@ -0,0 +1,36 @@
+// Pure web file-download primitive. Uses fetch+blob+anchor because
+// `window.open(url, "_blank")` is silently dropped by sandboxed iframes
+// (no `allow-popups`), and direct anchor navigation without the `download`
+// attribute doesn't trigger a save dialog for inline MIME types (HTML,
+// JSON, PDFs, etc.).
+//
+// `cache: "no-store"` avoids a CORS cache collision: if a prior <img>
+// loaded the same URL without an Origin header, the cached response
+// (missing Access-Control-Allow-Origin) gets reused for the fetch and
+// fails. Bypassing the cache forces a fresh CORS-aware request.
+//
+// No React Native / @lotics/shared imports — kept pure so both the host
+// frontend and sandboxed custom-code apps can consume via the per-file
+// export without dragging the wider UI surface.
+
+export async function downloadFileFromUrl(url: string, filename: string): Promise<void> {
+  if (!url) throw new Error("downloadFileFromUrl: empty url");
+
+  const response = await fetch(url, { cache: "no-store" });
+  if (!response.ok) {
+    throw new Error(`File download failed: ${response.status} ${response.statusText}`);
+  }
+
+  const blob = await response.blob();
+  const blobUrl = URL.createObjectURL(blob);
+  try {
+    const link = document.createElement("a");
+    link.href = blobUrl;
+    link.download = filename;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+  } finally {
+    URL.revokeObjectURL(blobUrl);
+  }
+}

package/src/ring_gauge.tsx

@@ -0,0 +1,72 @@
+import { View } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+
+export interface RingGaugeProps {
+  /** Progress value, 0–100. Clamped to that range. */
+  value: number;
+  /** Short label under the ring. */
+  label: string;
+  /** Optional one-line context under the label. */
+  caption?: string;
+  /** Diameter in px. Default 128. */
+  size?: number;
+  /** Ring stroke width in px. Default 12. */
+  thickness?: number;
+  /** Arc color. Default teal accent. */
+  color?: string;
+}
+
+/**
+ * Circular progress gauge — an at-a-glance ring for a 0–100% metric
+ * (on-time rate, SLA compliance, win rate). The percentage leads in the
+ * center; the track behind it shows the remaining-to-100 context. Pairs
+ * with `KPICard` (figures) — use a ring when the number IS a ratio to 100.
+ *
+ * Implementation: native HTML `<svg>` (like `Sparkline`) — Vite can't
+ * resolve react-native-svg's native paths, and the `<View>` wrapper
+ * preserves the RN layout surface. The arc starts at 12 o'clock
+ * (`rotate(-90)`) and grows clockwise via `strokeDasharray`.
+ */
+export function RingGauge(props: RingGaugeProps) {
+  const { value, label, caption, size = 140, thickness = 10, color = colors.teal[600] } = props;
+  const clamped = Math.max(0, Math.min(100, value));
+  const center = size / 2;
+  const radius = (size - thickness) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const dash = (clamped / 100) * circumference;
+
+  return (
+    <View style={{ alignItems: "center", gap: 12 }}>
+      <View style={{ width: size, height: size, alignItems: "center", justifyContent: "center" }}>
+        <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ position: "absolute" }}>
+          <circle cx={center} cy={center} r={radius} fill="none" stroke={colors.zinc[200]} strokeWidth={thickness} />
+          <circle
+            cx={center}
+            cy={center}
+            r={radius}
+            fill="none"
+            stroke={color}
+            strokeWidth={thickness}
+            strokeLinecap="round"
+            strokeDasharray={`${dash} ${circumference}`}
+            transform={`rotate(-90 ${center} ${center})`}
+          />
+        </svg>
+        <Text size="xxl" weight="semibold">
+          {Math.round(clamped)}%
+        </Text>
+      </View>
+      <View style={{ alignItems: "center", gap: 2 }}>
+        <Text size="sm" weight="medium">
+          {label}
+        </Text>
+        {caption ? (
+          <Text size="xs" color="muted">
+            {caption}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}

package/src/tokens.ts

@@ -3,9 +3,16 @@
  * Lotics surfaces (parent app, custom_code iframe apps, browser extension).
  *
  * The colors come from `colors.ts` (re-exported below) — same module
- * the parent app's React Native components consume via
- * `colors.zinc[900]` / `colors.background` / etc. The iframe runtime
- * emits these same values as CSS variables via {@link getCssVariables}.
+ * BOTH the parent app's and custom-code apps' components consume via
+ * `colors.zinc[900]` / `colors.background` / etc. Custom-code apps use
+ * `@lotics/ui` components directly (rendered through react-native-web; the
+ * starter scaffold wires the alias — see `docs/apps.md`), so they self-theme
+ * via the same `colors` module with no CSS variables involved.
+ *
+ * {@link getCssVariables} is an OPT-IN helper that serializes these tokens to
+ * `--lotics-*` CSS variables for apps that hand-roll plain DOM/CSS instead of
+ * using `@lotics/ui` components. Nothing injects them automatically — the
+ * runtime does NOT emit them, and the component path does not need them.
  *
  * **CSS variable naming mirrors the parent's TS references 1:1**:
  *   colors.zinc[900]    → var(--lotics-zinc-900)
@@ -86,8 +93,11 @@ export const radius = {
 
 /**
  * Emit a CSS string defining all design tokens as `:root` custom
- * properties. Used by the iframe runtime so plain-DOM components can
- * consume the same palette as the parent app's React Native components.
+ * properties. OPT-IN: an app that hand-rolls plain DOM/CSS (instead of
+ * using `@lotics/ui` components, which self-theme via the `colors` module)
+ * can inject this to consume the same palette. Nothing calls it
+ * automatically — there is no runtime that emits it; the component path
+ * doesn't need it.
  *
  * Variable names mirror `colors` 1:1 — palette entries (zinc, red,
  * etc.) emit as `--lotics-<name>-<shade>`, top-level entries (black,