@hexclave/shared 1.0.2 → 1.0.5

package/src/apps/apps-config.ts

@@ -0,0 +1,177 @@
+type AppTag = {
+  displayName: string,
+};
+
+export const ALL_APP_TAGS = {
+  "expert": {
+    displayName: "Expert",
+  },
+  "integration": {
+    displayName: "Integrations",
+  },
+  "auth": {
+    displayName: "Authentication",
+  },
+  "developers": {
+    displayName: "For Developers",
+  },
+  "security": {
+    displayName: "Security",
+  },
+  "operations": {
+    displayName: "For Operations",
+  },
+  "gtm": {
+    displayName: "Go-to-market",
+  },
+  "comms": {
+    displayName: "Communications",
+  },
+  "automation": {
+    displayName: "Automation",
+  },
+  "storage": {
+    displayName: "Storage & Databases",
+  },
+  "various": {
+    displayName: "Various",
+  },
+} as const satisfies Record<string, AppTag>;
+
+type App = {
+  displayName: string,
+  subtitle: string,
+  tags: (keyof typeof ALL_APP_TAGS)[],
+  stage: "alpha" | "beta" | "stable",
+};
+
+export type AppId = keyof typeof ALL_APPS;
+
+export const ALL_APPS = {
+  "authentication": {
+    displayName: "Authentication",
+    subtitle: "User sign-in and account management",
+    tags: ["auth", "security"],
+    stage: "stable",
+  },
+  "fraud-protection": {
+    displayName: "Fraud Protection",
+    subtitle: "Protect your project from fraud and abuse",
+    tags: ["auth", "security"],
+    stage: "stable",
+  },
+  "onboarding": {
+    displayName: "Onboarding",
+    subtitle: "Configure user onboarding requirements",
+    tags: ["auth"],
+    stage: "alpha",
+  },
+  "teams": {
+    displayName: "Teams",
+    subtitle: "Team collaboration and management",
+    tags: ["auth", "security"],
+    stage: "stable",
+  },
+  "rbac": {
+    displayName: "RBAC",
+    subtitle: "Role-based access control and permissions",
+    tags: ["auth", "security"],
+    stage: "stable",
+  },
+  "api-keys": {
+    displayName: "API Keys",
+    subtitle: "API key generation and management",
+    tags: ["auth", "security", "developers"],
+    stage: "stable",
+  },
+  "payments": {
+    displayName: "Payments",
+    subtitle: "Payment processing and subscription management",
+    tags: ["operations", "gtm"],
+    stage: "beta",
+  },
+  "emails": {
+    displayName: "Emails",
+    subtitle: "Email template configuration and management",
+    tags: ["comms"],
+    stage: "stable",
+  },
+  "support": {
+    displayName: "Support",
+    subtitle: "Customer conversations, team replies, and internal notes",
+    tags: ["comms", "operations"],
+    stage: "alpha",
+  },
+  "email-api": {
+    displayName: "Email API",
+    subtitle: "Programmatic email sending and delivery",
+    tags: ["comms", "developers", "expert"],
+    stage: "alpha",
+  },
+  "data-vault": {
+    displayName: "Data Vault",
+    subtitle: "Secure storage for sensitive user data",
+    tags: ["security", "storage"],
+    stage: "beta",
+  },
+  "webhooks": {
+    displayName: "Webhooks",
+    subtitle: "Real-time event notifications and integrations",
+    tags: ["developers"],
+    stage: "stable",
+  },
+  "tv-mode": {
+    displayName: "TV mode",
+    subtitle: "Dashboard display for large screens",
+    tags: ["various"],
+    stage: "alpha",
+  },
+  "launch-checklist": {
+    displayName: "Launch Checklist",
+    subtitle: "Pre-launch verification and readiness checks",
+    tags: ["various"],
+    stage: "stable",
+  },
+  "catalyst": {
+    displayName: "Catalyst",
+    subtitle: "Project scaffolding and rapid development",
+    tags: ["various"],
+    stage: "alpha",
+  },
+  "neon": {
+    displayName: "Neon Integration",
+    subtitle: "Serverless Postgres database integration",
+    tags: ["integration", "storage"],
+    stage: "alpha",
+  },
+  "convex": {
+    displayName: "Convex Integration",
+    subtitle: "Real-time backend platform integration",
+    tags: ["integration", "storage"],
+    stage: "alpha",
+  },
+  "vercel": {
+    displayName: "Vercel Integration",
+    subtitle: "Deploy your Hexclave project to Vercel",
+    tags: ["integration", "developers"],
+    stage: "stable",
+  },
+  "tanstack-start": {
+    displayName: "TanStack Start",
+    subtitle: "Use Hexclave in TanStack Start apps",
+    tags: ["integration", "developers"],
+    stage: "alpha",
+  },
+  "analytics": {
+    displayName: "Analytics",
+    subtitle: "View and explore analytics data",
+    tags: ["developers", "operations"],
+    stage: "stable",
+  },
+  "session-replays": {
+    displayName: "Session Replays",
+    subtitle: "Watch real user sessions to understand how people use your app",
+    tags: ["developers", "operations"],
+    stage: "stable",
+  },
+} as const satisfies Record<string, App>;

package/src/apps/apps-ui.tsx

@@ -0,0 +1,112 @@
+import React from "react";
+import { AppId } from "./apps-config";
+
+export const appSquareWidthExpression = "max(min(11vw,180px),80px)";
+export const appSquarePaddingExpression = "max(min(1vw,1.5rem),0.25rem)";
+
+export type AppIconProps = {
+  appId: AppId,
+  /**
+   * Icon component from the app frontend config
+   */
+  IconComponent: React.FunctionComponent<React.SVGProps<SVGSVGElement>>,
+  /**
+   * Optional logo component from the app frontend config
+   */
+  LogoComponent?: React.FunctionComponent<{}>,
+  className?: string,
+  /**
+   * Whether this app is enabled/installed (shows green icon)
+   */
+  enabled?: boolean,
+  /**
+   * Whether this app is disabled (shows dashed border)
+   */
+  disabled?: boolean,
+  style?: React.CSSProperties,
+  /**
+   * cn utility function for className merging (e.g., from stack-ui or tailwind-merge)
+   */
+  cn: (...inputs: any[]) => string,
+};
+
+export function AppIcon({
+  appId,
+  IconComponent,
+  LogoComponent,
+  className,
+  enabled = false,
+  disabled,
+  style,
+  cn,
+}: AppIconProps) {
+
+  const filterId = "glow-fx";
+
+  return (
+    <>
+      {/* theoretically, this only needs to be in the dom once: */}
+      <svg height="0" width="0" style={{ position: "absolute", marginLeft: "-100%" }}>
+        <defs>
+          <filter id={filterId} colorInterpolationFilters="sRGB" x="-50%" y="-50%" width="200%" height="200%">
+            {/* drop shadow */}
+            <feOffset dx="0" dy="2" in="SourceAlpha" result="dropOffset" />
+            <feGaussianBlur stdDeviation="8" in="dropOffset" result="dropBlur" />
+            <feFlood floodColor="#4271FF" floodOpacity="0.8" result="dropFlood" />
+            <feComposite operator="in" in="dropFlood" in2="dropBlur" result="dropShadow" />
+            {/* outer shadow */}
+            <feOffset dx="0" dy="0" in="SourceAlpha" result="outerOffset" />
+            <feGaussianBlur stdDeviation="4" in="outerOffset" result="outerBlur" />
+            <feFlood floodColor="#00BBFF" floodOpacity="0.3" result="outerFlood" />
+            <feComposite operator="in" in="outerFlood" in2="outerBlur" result="outerShadow" />
+            {/* Combine: drop shadow behind, then outer shadow, then source graphic on top */}
+            <feComposite operator="over" in="outerShadow" in2="dropShadow" result="combinedShadows" />
+            <feComposite operator="over" in="SourceGraphic" in2="combinedShadows" />
+          </filter>
+        </defs>
+      </svg>
+      <div
+        style={style}
+        className={cn(
+          "relative w-[72px] h-[72px] overflow-hidden select-none",
+          "rounded-[20%] supports-[corner-shape:superellipse(1.5)]:[border-radius:30%] supports-[corner-shape:superellipse(1.5)]:[corner-shape:superellipse(1.5)]",  // https://x.com/konstiwohlwend/status/1991221528206405685
+          "shadow-[0_4px_12px_0_rgba(0,0,0,0.08)] dark:!shadow-[0_10px_24px_0_rgba(10,69,151,0.28)]",
+          "before:absolute before:inset-0 before:bg-gradient-to-br before:from-slate-300 before:via-slate-400 before:to-slate-300 dark:before:from-[#4E7598] dark:before:via-[#0D233D] dark:before:to-[#4E7598] before:rounded-[inherit] before:supports-[corner-shape:superellipse(1.5)]:[border-radius:30%] before:supports-[corner-shape:superellipse(1.5)]:[corner-shape:superellipse(1.5)]",
+          // !disabled && "bg-gray-300 dark:bg-gray-900",
+          // disabled && 'bg-gray-300 dark:bg-gray-900',
+          className,
+        )}
+      >
+        <div className={cn("absolute inset-[1px] isolate flex items-center justify-center rounded-[inherit] supports-[corner-shape:superellipse(1.5)]:[border-radius:30%] supports-[corner-shape:superellipse(1.5)]:[corner-shape:superellipse(1.5)]", !disabled && "bg-gradient-to-br from-slate-100 to-slate-200 dark:from-[#163050] dark:to-[#090C11]", disabled && "bg-gray-300 dark:bg-gray-900")}>
+          {LogoComponent ? (
+            <div
+              className={cn(
+                "w-[42%] h-[42%] flex items-center justify-center",
+                "[&_svg]:overflow-visible",
+                !enabled && "grayscale opacity-60"
+              )}
+              style={{ filter: `url(#${filterId})` }}
+            >
+              <LogoComponent />
+            </div>
+          ) : (
+            <IconComponent
+              className={cn(
+                "w-[42%] h-[42%]",
+                enabled
+                  ? "stroke-emerald-600 dark:stroke-emerald-400"
+                  : "stroke-slate-500 dark:stroke-gray-500"
+              )}
+              style={{
+                opacity: disabled ? 0.5 : 1,
+                filter: `url(#${filterId})`,
+              }}
+              overflow="visible"
+            />
+          )}
+        </div>
+      </div>
+    </>
+  );
+}
+

package/src/config/README.md

@@ -0,0 +1,154 @@
+# Some notes on configs
+
+The language in this file is very technical, if you're struggling, put it into ChatGPT and see if it can help you (with the usual hallucination disclaimer).
+ 
+## Generic format vs. Hexclave
+
+The config format is generally usable and not specific to Hexclave.
+
+All the logic required for generic usage of the config format are in `format/`. The other files in this folder are specific to Hexclave's usage of it.
+
+## Terminology
+
+**Generic config format**:
+- Config: Any config, as described in stack-info
+- Normalized config: A config without `null` fields and dot notation
+
+**Hexclave**: There are four levels, project, branch, environment, organization.
+- Base config: The defaults that come with Hexclave
+- `$Level` config override: Overrides that are applied to the base config (in the following order: project -> branch -> environment -> organization)
+- `$Level` incomplete config: The base config after some overrides have been applied
+- `$Level` rendered config: An incomplete config with those fields removed that can be overridden by a future override, deeply merged into the defaults and sanitized (using `apply{$Level}DefaultsAndSanitize`), and then normalized
+- Complete config: The organization rendered config.
+- `$Level` config override override: An override that overrides the `$Level` config override. This is most often used eg. in the REST API to let users make changes to the branch-level config, without overwriting the entire branch-level config override. *<sup>Note that, since config overrides (unlike configs) distinguish between `null` and a property missing (`undefined`), it is currently not possible to say "this property in the config override should be unset" (setting a property to `null` in the override override will simply also set it to `null` in the override). In the future, we'll have to think about how we handle this, probably with a sentinel value.</sup>*
+- `$Level` config: Could refer to any of the above, depending on the context; if it's not clear, specify it.
+
+<details>
+<summary>Examples</summary>
+
+Base config:
+```js
+{
+  organizations: {},
+  createTeamOnSignUp: false,
+  sourceOfTruthConnectionString: null
+}
+```
+
+---
+
+Project config override:
+```js
+{
+  sourceOfTruthConnectionString: 'postgresql://...',
+}
+```
+
+Project incomplete config:
+```js
+// note: `organizations` and `createTeamOnSignUp` may be overridden by branch, environment, or organization configs! They are not final
+{
+  organizations: {},
+  createTeamOnSignUp: false,
+  sourceOfTruthConnectionString: 'postgresql://...',
+}
+```
+
+Project rendered config:
+```js
+// since `organizations` and `createTeamOnSignUp` may change later, they are not included in the rendered config
+{
+  sourceOfTruthConnectionString: 'postgresql://...',
+}
+```
+
+---
+
+Branch config override:
+```js
+{
+  organizations: {
+    'my-org': {
+      name: 'My Org',
+    }
+  }
+}
+```
+
+
+Branch incomplete config:
+```js
+{
+  organizations: {
+    'my-org': {
+      name: 'My Org',
+    }
+  },
+  createTeamOnSignUp: true,
+  sourceOfTruthConnectionString: 'postgresql://...',
+}
+```
+
+Branch rendered config:
+```js
+// as above, `organizations` and `createTeamOnSignUp` are not included in the rendered config, as they may change later
+{
+  sourceOfTruthConnectionString: 'postgresql://...',
+}
+```
+
+---
+
+Environment config override:
+```js
+// no change from branch config
+{}
+```
+
+Environment incomplete config:
+```js
+// no change from branch config
+{
+  organizations: {
+    'my-org': {
+      name: 'My Org',
+    }
+  },
+  createTeamOnSignUp: true,
+  sourceOfTruthConnectionString: 'postgresql://...',
+}
+```
+
+Environment rendered config:
+```js
+// organizations can no longer change after this point, so they are included in the rendered config
+{
+  organizations: {
+    'my-org': {
+      name: 'My Org',
+    }
+  },
+  createTeamOnSignUp: true,
+  sourceOfTruthConnectionString: 'postgresql://...',
+}
+```
+
+---
+
+Organization config override:
+```js
+{
+  createTeamOnSignUp: true,
+}
+```
+
+Organization incomplete config = organization rendered config = complete config:
+```js
+{
+  createTeamOnSignUp: true,
+  sourceOfTruthConnectionString: 'postgresql://...',
+}
+```
+
+
+</details>