alepha 0.15.4 → 0.15.5

package/src/react/intro/components/GettingStarted.css

@@ -0,0 +1,334 @@
+.alepha-blank {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100svh;
+  background: #fafafa;
+  font-family: system-ui, -apple-system, sans-serif;
+  color: #171717;
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  top: 0;
+  width: 100%;
+}
+
+.alepha-blank-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  max-width: 640px;
+}
+
+.alepha-blank-text-block {
+  min-height: 320px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Message */
+
+.alepha-blank-message {
+  font-size: clamp(2rem, 8vw, 3rem);
+  font-weight: 600;
+  letter-spacing: -0.02em;
+  margin: 0;
+  line-height: 1.1;
+}
+
+.alepha-blank-sub {
+  font-size: 1.0625rem;
+  color: #525252;
+  margin: 1rem 0 0;
+  font-weight: 400;
+  line-height: 1.5;
+}
+
+.alepha-blank-detail {
+  font-size: 0.875rem;
+  color: #a3a3a3;
+  margin: 0.5rem 0 0;
+  font-weight: 400;
+  line-height: 1.5;
+}
+
+/* Slide Animations */
+
+.alepha-blank-slide-next {
+  animation: alepha-blank-slideNext 0.4s cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+.alepha-blank-slide-prev {
+  animation: alepha-blank-slidePrev 0.4s cubic-bezier(0.22, 1, 0.36, 1) both;
+}
+
+@keyframes alepha-blank-slideNext {
+  from {
+    opacity: 0;
+    transform: translateX(20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes alepha-blank-slidePrev {
+  from {
+    opacity: 0;
+    transform: translateX(-20px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+/* Steps */
+
+.alepha-blank-steps {
+  display: flex;
+  flex-direction: column;
+  gap: 0.25rem;
+  margin-top: 1.25rem;
+  text-align: left;
+}
+
+.alepha-blank-step {
+  display: flex;
+  align-items: center;
+  gap: 0.625rem;
+  padding: 0.25rem 0;
+  opacity: 0;
+  animation: alepha-blank-stepIn 0.4s cubic-bezier(0.22, 1, 0.36, 1) forwards;
+}
+
+.alepha-blank-step-num {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  border-radius: 50%;
+  background: #171717;
+  color: #fff;
+  font-size: 0.6875rem;
+  font-weight: 600;
+  flex-shrink: 0;
+}
+
+.alepha-blank-step-text {
+  font-size: 0.8125rem;
+  color: #525252;
+  line-height: 1.5;
+}
+
+.alepha-blank-step-text code {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.75rem;
+  background: #f5f5f5;
+  color: #171717;
+  padding: 0.0625rem 0.375rem;
+  border-radius: 3px;
+  border: 1px solid #e5e5e5;
+}
+
+.alepha-blank-step-text a {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  color: #525252;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+  transition: color 0.15s ease;
+}
+
+.alepha-blank-step-text a:hover {
+  color: #171717;
+}
+
+@keyframes alepha-blank-stepIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Links */
+
+.alepha-blank-links {
+  display: flex;
+  gap: 1.5rem;
+  margin-top: 1.25rem;
+}
+
+.alepha-blank-links a {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.875rem;
+  color: #525252;
+  text-decoration: none;
+  position: relative;
+  opacity: 0;
+  animation: alepha-blank-fadeIn 0.3s ease-out forwards;
+  transition: color 0.2s ease;
+}
+
+.alepha-blank-links a::after {
+  content: "";
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: -2px;
+  height: 1px;
+  background: #a3a3a3;
+  transform: scaleX(1);
+  transform-origin: left;
+  transition:
+    transform 0.25s cubic-bezier(0.22, 1, 0.36, 1),
+    background 0.2s ease;
+}
+
+.alepha-blank-links a:hover {
+  color: #171717;
+}
+
+.alepha-blank-links a:hover::after {
+  background: #171717;
+  transform: scaleX(1.05);
+}
+
+/* Slider */
+
+.alepha-blank-slider {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  margin-top: 2.5rem;
+}
+
+.alepha-blank-dots {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.alepha-blank-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: transparent;
+  border: 1.5px solid #d4d4d4;
+  padding: 0;
+  cursor: pointer;
+  transition: all 0.25s cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.alepha-blank-dot:hover {
+  border-color: #a3a3a3;
+  transform: scale(1.2);
+}
+
+.alepha-blank-dot:focus-visible {
+  outline: 2px solid #737373;
+  outline-offset: 2px;
+}
+
+.alepha-blank-dot.active {
+  background: #737373;
+  border-color: #737373;
+  transform: scale(1.1);
+}
+
+/* Nav Buttons */
+
+.alepha-blank-nav-btn {
+  width: 32px;
+  height: 32px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  font-family: inherit;
+  background: transparent;
+  color: #a3a3a3;
+  border: 1.5px solid transparent;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.2s cubic-bezier(0.22, 1, 0.36, 1);
+}
+
+.alepha-blank-nav-btn:hover {
+  color: #525252;
+  background: #f0f0f0;
+}
+
+.alepha-blank-nav-btn:focus-visible {
+  outline: none;
+  border-color: #737373;
+  color: #525252;
+}
+
+.alepha-blank-nav-btn:active {
+  transform: scale(0.92);
+  background: #e5e5e5;
+}
+
+/* Hint */
+
+.alepha-blank-hint {
+  margin-top: 2rem;
+  font-size: 0.75rem;
+  color: #a3a3a3;
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+  opacity: 0;
+  animation: alepha-blank-fadeIn 0.5s ease-out 0.5s forwards;
+}
+
+.alepha-blank-hint kbd {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.6875rem;
+  background: #f0f0f0;
+  border: 1px solid #e5e5e5;
+  border-radius: 4px;
+  padding: 0.125rem 0.375rem;
+  box-shadow: 0 1px 0 #d4d4d4;
+}
+
+/* Fade In Animation */
+
+@keyframes alepha-blank-fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+/* Respect reduced motion */
+
+@media (prefers-reduced-motion: reduce) {
+  .alepha-blank-slide-next,
+  .alepha-blank-slide-prev,
+  .alepha-blank-links a,
+  .alepha-blank-hint,
+  .alepha-blank-step {
+    animation: none;
+    opacity: 1;
+  }
+
+  .alepha-blank-dot,
+  .alepha-blank-nav-btn,
+  .alepha-blank-links a,
+  .alepha-blank-links a::after {
+    transition: none;
+  }
+}

package/src/react/intro/components/GettingStarted.tsx

@@ -0,0 +1,276 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import "./GettingStarted.css";
+import { useRouter } from "alepha/react/router";
+import type { ReactNode } from "react";
+
+type Step = {
+  num: string;
+  text: ReactNode;
+};
+
+type Message = {
+  text: string;
+  sub: string;
+  detail?: string;
+  steps?: Step[];
+  links?: { label: string; href: string }[];
+};
+
+const messages: Message[] = [
+  {
+    text: "Let's begin.",
+    sub: "Every story starts with a blank page.",
+    detail: "This one is yours.",
+  },
+  {
+    text: "Need help?",
+    sub: "We've got you covered.",
+    detail: "Even our AI friends can read the docs.",
+    links: [
+      { label: "alepha.dev", href: "https://alepha.dev" },
+      { label: "llms.txt", href: "https://alepha.dev/llms.txt" },
+    ],
+  },
+];
+
+/**
+ * A welcome component displayed when creating a new Alepha application.
+ */
+const GettingStarted = () => {
+  const [index, setIndex] = useState(0);
+  const [direction, setDirection] = useState<"next" | "prev">("next");
+
+  const router = useRouter();
+  const hasAdmin = router.pages.find((it) => it.name === "adminLayout");
+  const hasAuth = router.pages.find((it) => it.name === "authLayout");
+
+  const adminAnchorProps = hasAdmin
+    ? router.anchor(router.path("adminLayout"))
+    : undefined;
+  const authAnchorProps = hasAuth
+    ? router.anchor(router.path("login"))
+    : undefined;
+
+  const filteredMessages = useMemo(() => {
+    const result: Message[] = [];
+
+    // Add static messages up to "What's next?"
+    for (const msg of messages) {
+      if (msg.text === "Need help?") break;
+      result.push(msg);
+    }
+
+    // Add auth message if available
+    if (hasAuth && authAnchorProps) {
+      result.push({
+        text: "Who are you?",
+        sub: "Create your first account.",
+        steps: [
+          {
+            num: "1",
+            text: (
+              <>
+                Sign up at <a {...authAnchorProps}>/auth/login</a>
+              </>
+            ),
+          },
+          {
+            num: "2",
+            text: (
+              <>
+                Customize in <code>src/api/AppSecurity.ts</code>
+              </>
+            ),
+          },
+        ],
+      });
+    }
+
+    // Add admin message if available
+    if (hasAdmin && adminAnchorProps) {
+      result.push({
+        text: "Take the wheel.",
+        sub: "Become admin in three steps.",
+        steps: [
+          {
+            num: "1",
+            text: (
+              <>
+                Add your email to <code>adminEmails</code> in{" "}
+                <code>AppSecurity.ts</code>
+              </>
+            ),
+          },
+          { num: "2", text: "Create a user account with that email" },
+          {
+            num: "3",
+            text: (
+              <>
+                Go to <a {...adminAnchorProps}>/admin</a>
+              </>
+            ),
+          },
+        ],
+      });
+    }
+
+    // Add "Need help?" message
+    const helpMsg = messages.find((msg) => msg.text === "Need help?");
+    if (helpMsg) {
+      result.push(helpMsg);
+    }
+
+    return result;
+  }, [hasAuth, hasAdmin, authAnchorProps, adminAnchorProps]);
+
+  const current = filteredMessages[index];
+
+  const prev = useCallback(() => {
+    setDirection("prev");
+    setIndex(
+      (i) => (i - 1 + filteredMessages.length) % filteredMessages.length,
+    );
+  }, [filteredMessages.length]);
+
+  const next = useCallback(() => {
+    setDirection("next");
+    setIndex((i) => (i + 1) % filteredMessages.length);
+  }, [filteredMessages.length]);
+
+  const goTo = useCallback(
+    (i: number) => {
+      setDirection(i > index ? "next" : "prev");
+      setIndex(i);
+    },
+    [index],
+  );
+
+  useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === "ArrowLeft") {
+        prev();
+      } else if (e.key === "ArrowRight") {
+        next();
+      }
+    };
+    window.addEventListener("keydown", handleKeyDown);
+    return () => window.removeEventListener("keydown", handleKeyDown);
+  }, [prev, next]);
+
+  return (
+    <main className="alepha-blank">
+      <div className="alepha-blank-content">
+        <div className="alepha-blank-text-block">
+          <h1
+            className={`alepha-blank-message alepha-blank-slide-${direction}`}
+            key={index}
+          >
+            {current.text}
+          </h1>
+          <p
+            className={`alepha-blank-sub alepha-blank-slide-${direction}`}
+            key={`sub-${index}`}
+          >
+            {current.sub}
+          </p>
+          {current.detail && (
+            <p
+              className={`alepha-blank-detail alepha-blank-slide-${direction}`}
+              key={`detail-${index}`}
+            >
+              {current.detail}
+            </p>
+          )}
+          {current.steps && (
+            <div
+              className={`alepha-blank-steps alepha-blank-slide-${direction}`}
+              key={`steps-${index}`}
+            >
+              {current.steps.map((step, i) => (
+                <div
+                  key={i}
+                  className="alepha-blank-step"
+                  style={{ animationDelay: `${0.15 + i * 0.08}s` }}
+                >
+                  <span className="alepha-blank-step-num">{step.num}</span>
+                  <span className="alepha-blank-step-text">{step.text}</span>
+                </div>
+              ))}
+            </div>
+          )}
+          {current.links && (
+            <div
+              className={`alepha-blank-links alepha-blank-slide-${direction}`}
+              key={`links-${index}`}
+            >
+              {current.links.map((link, i) => (
+                <a
+                  key={link.href}
+                  href={link.href}
+                  target={link.href.startsWith("http") ? "_blank" : undefined}
+                  rel={
+                    link.href.startsWith("http")
+                      ? "noopener noreferrer"
+                      : undefined
+                  }
+                  style={{ animationDelay: `${0.1 + i * 0.05}s` }}
+                >
+                  {link.label}
+                </a>
+              ))}
+            </div>
+          )}
+        </div>
+
+        <div className="alepha-blank-slider">
+          <button
+            className="alepha-blank-nav-btn"
+            onClick={prev}
+            aria-label="Previous"
+          >
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+              <path
+                d="M9 3L5 7L9 11"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+            </svg>
+          </button>
+          <div className="alepha-blank-dots">
+            {filteredMessages.map((_, i) => (
+              <button
+                key={i}
+                className={`alepha-blank-dot ${i === index ? "active" : ""}`}
+                onClick={() => goTo(i)}
+                aria-label={`Go to message ${i + 1}`}
+              />
+            ))}
+          </div>
+          <button
+            className="alepha-blank-nav-btn"
+            onClick={next}
+            aria-label="Next"
+          >
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
+              <path
+                d="M5 3L9 7L5 11"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              />
+            </svg>
+          </button>
+        </div>
+
+        <div className="alepha-blank-hint">
+          <kbd>←</kbd> <kbd>→</kbd> to navigate
+        </div>
+      </div>
+    </main>
+  );
+};
+
+export default GettingStarted;

package/src/react/intro/index.ts

@@ -0,0 +1 @@
+export { default as GettingStarted } from "./components/GettingStarted.tsx";

package/src/react/router/index.browser.ts

@@ -1,6 +1,7 @@
 import { $module } from "alepha";
 import { AlephaDateTime } from "alepha/datetime";
 import { AlephaReact } from "alepha/react";
+import { AlephaReactHead } from "alepha/react/head";
 import { AlephaServer } from "alepha/server";
 import { AlephaServerLinks } from "alepha/server/links";
 import { $page } from "./primitives/$page.ts";
@@ -34,6 +35,7 @@ export const AlephaReactRouter = $module({
   register: (alepha) =>
     alepha
       .with(AlephaReact)
+      .with(AlephaReactHead)
       .with(AlephaDateTime)
       .with(AlephaServer)
       .with(AlephaServerLinks)

package/src/react/router/index.ts

@@ -1,6 +1,7 @@
 import { $module } from "alepha";
 import { AlephaDateTime } from "alepha/datetime";
 import { AlephaReact } from "alepha/react";
+import { AlephaReactHead } from "alepha/react/head";
 import { AlephaServer, type ServerRequest } from "alepha/server";
 import { AlephaServerCache } from "alepha/server/cache";
 import { AlephaServerLinks } from "alepha/server/links";
@@ -129,6 +130,7 @@ export const AlephaReactRouter = $module({
   register: (alepha) =>
     alepha
       .with(AlephaReact)
+      .with(AlephaReactHead)
       .with(AlephaDateTime)
       .with(AlephaServer)
       .with(AlephaServerCache)

package/src/redis/index.ts

@@ -18,9 +18,9 @@ export * from "./providers/RedisSubscriberProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.1.0 | node, bun|
  *
  * Redis client wrapper.
  *

package/src/retry/index.ts

@@ -12,9 +12,9 @@ export * from "./providers/RetryProvider.ts";
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.12.0 | node, bun, workerd, browser, expo|
  *
  * Automatic retry with backoff.
  *

package/src/router/index.ts

@@ -1,7 +1,7 @@
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | frontend | standard | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.2.0 | node, bun, workerd, browser, expo|
  *
  * Frontend routing infrastructure.
  *

package/src/scheduler/index.ts

@@ -35,9 +35,9 @@ declare module "alepha" {
 // ---------------------------------------------------------------------------------------------------------------------
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | rare | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.1.0 | node, bun, workerd|
  *
  * Cron and interval-based task execution.
  *

package/src/security/index.ts

@@ -89,9 +89,9 @@ declare module "alepha/server" {
 }
 
 /**
- * | type | quality | stability |
- * |------|---------|-----------|
- * | backend | epic | stable |
+ * | Stability | Since | Runtime |
+ * |-----------|-------|---------|
+ * | 3 - stable | 0.1.0 | node, bun, workerd, browser|
  *
  * Complete authentication and authorization system with JWT, RBAC, and multi-issuer support.
  *