@jcsoftdev/ui 0.0.0-stage → 0.1.1

package/src/rich-text/sanitize.ts

@@ -0,0 +1,266 @@
+/**
+ * Allowlist HTML sanitizer for the rich text editor. It is a small string tokenizer with no DOM
+ * dependency, so it runs the same on the server, in the browser and in tests.
+ *
+ * Rules:
+ * - Only the tags in `ALLOWED_TAGS` survive, and only without attributes, except `<a href>`.
+ * - Unknown tags are unwrapped (their text stays); `DROP_WITH_CONTENT` tags lose their content too.
+ * - `href` must be http(s), mailto, tel, or a relative/fragment link. Everything else
+ *   (javascript:, data:, vbscript:, ...) is removed after entity decoding and control-char stripping.
+ * - Output is rebuilt from tokens, always re-escaped and always balanced.
+ */
+
+const ALLOWED_TAGS = new Set([
+  "p",
+  "br",
+  "strong",
+  "em",
+  "u",
+  "s",
+  "ul",
+  "ol",
+  "li",
+  "a",
+  "h2",
+  "h3",
+  "blockquote",
+]);
+
+/** Equivalent tags are renamed so the output vocabulary stays small. */
+const TAG_ALIASES: Record<string, string> = {
+  b: "strong",
+  i: "em",
+  strike: "s",
+  del: "s",
+  h1: "h2",
+  h4: "h3",
+  h5: "h3",
+  h6: "h3",
+  div: "p",
+};
+
+const DROP_WITH_CONTENT = new Set([
+  "script",
+  "style",
+  "iframe",
+  "object",
+  "embed",
+  "svg",
+  "math",
+  "template",
+  "noscript",
+  "textarea",
+  "select",
+  "title",
+  "head",
+  "frameset",
+  "applet",
+  "xmp",
+  "noembed",
+  "noframes",
+  "plaintext",
+]);
+
+const VOID_TAGS = new Set(["br"]);
+
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+  colon: ":",
+  tab: "\t",
+  newline: "\n",
+  sol: "/",
+};
+
+function decodeEntities(text: string): string {
+  return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z][a-z0-9]*);?/gi, (match, body: string) => {
+    if (body[0] === "#") {
+      const code =
+        body[1]?.toLowerCase() === "x" ? Number.parseInt(body.slice(2), 16) : Number(body.slice(1));
+      if (!Number.isFinite(code) || code <= 0 || code > 0x10ffff) return "";
+      return String.fromCodePoint(code);
+    }
+    return NAMED_ENTITIES[body.toLowerCase()] ?? match;
+  });
+}
+
+function escapeText(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function escapeAttribute(text: string): string {
+  return escapeText(text).replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+function isInvisible(code: number): boolean {
+  return (
+    code <= 0x20 ||
+    (code >= 0x7f && code <= 0x9f) ||
+    (code >= 0x200b && code <= 0x200d) ||
+    code === 0x2028 ||
+    code === 0x2029 ||
+    code === 0xfeff
+  );
+}
+
+/** True for http(s), mailto, tel and scheme-less (relative or fragment) URLs. */
+export function isSafeUrl(raw: string): boolean {
+  // Browsers ignore control characters and whitespace inside the scheme ("java\tscript:").
+  const url = Array.from(decodeEntities(raw))
+    .filter((char) => !isInvisible(char.codePointAt(0) ?? 0))
+    .join("");
+  if (url === "") return false;
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(url);
+  if (!scheme) return true;
+  return ["http", "https", "mailto", "tel"].includes((scheme[1] ?? "").toLowerCase());
+}
+
+interface ParsedTag {
+  name: string;
+  closing: boolean;
+  attributes: Record<string, string>;
+  end: number;
+}
+
+function parseTag(html: string, start: number): ParsedTag | null {
+  const match = /^<(\/?)([a-zA-Z][a-zA-Z0-9:-]*)/.exec(html.slice(start, start + 64));
+  if (!match) return null;
+  let i = start + match[0].length;
+  const attributes: Record<string, string> = {};
+  const length = html.length;
+  while (i < length) {
+    while (i < length && /[\s/]/.test(html[i] as string)) i++;
+    if (html[i] === ">")
+      return {
+        name: (match[2] as string).toLowerCase(),
+        closing: match[1] === "/",
+        attributes,
+        end: i + 1,
+      };
+    const nameStart = i;
+    while (i < length && !/[\s/=>]/.test(html[i] as string)) i++;
+    const name = html.slice(nameStart, i).toLowerCase();
+    while (i < length && /\s/.test(html[i] as string)) i++;
+    let value = "";
+    if (html[i] === "=") {
+      i++;
+      while (i < length && /\s/.test(html[i] as string)) i++;
+      const quote = html[i];
+      if (quote === '"' || quote === "'") {
+        const close = html.indexOf(quote, i + 1);
+        const stop = close === -1 ? length : close;
+        value = html.slice(i + 1, stop);
+        i = stop + 1;
+      } else {
+        const valueStart = i;
+        while (i < length && !/[\s>]/.test(html[i] as string)) i++;
+        value = html.slice(valueStart, i);
+      }
+    }
+    if (name && !(name in attributes)) attributes[name] = value;
+  }
+  // Unterminated tag: drop the remainder (an empty name is never allowed).
+  return {
+    name: "",
+    closing: match[1] === "/",
+    attributes,
+    end: length,
+  };
+}
+
+/** Returns safe, balanced HTML containing only the editor's vocabulary. */
+export function sanitizeHtml(input: string): string {
+  const html = String(input ?? "");
+  const out: string[] = [];
+  const stack: string[] = [];
+  let i = 0;
+
+  const closeTo = (name: string) => {
+    const at = stack.lastIndexOf(name);
+    if (at === -1) return;
+    while (stack.length > at) out.push(`</${stack.pop()}>`);
+  };
+
+  while (i < html.length) {
+    const lt = html.indexOf("<", i);
+    if (lt === -1) {
+      out.push(escapeText(decodeEntities(html.slice(i))));
+      break;
+    }
+    if (lt > i) out.push(escapeText(decodeEntities(html.slice(i, lt))));
+
+    if (html.startsWith("<!--", lt)) {
+      const close = html.indexOf("-->", lt + 4);
+      i = close === -1 ? html.length : close + 3;
+      continue;
+    }
+    if (html[lt + 1] === "!" || html[lt + 1] === "?") {
+      const close = html.indexOf(">", lt);
+      i = close === -1 ? html.length : close + 1;
+      continue;
+    }
+
+    const tag = parseTag(html, lt);
+    if (!tag) {
+      out.push("&lt;");
+      i = lt + 1;
+      continue;
+    }
+    i = tag.end;
+
+    if (!tag.closing && DROP_WITH_CONTENT.has(tag.name)) {
+      const closer = new RegExp(`</${tag.name}[\\s/>]`, "i").exec(html.slice(i));
+      if (!closer) {
+        i = html.length;
+      } else {
+        const close = html.indexOf(">", i + closer.index);
+        i = close === -1 ? html.length : close + 1;
+      }
+      continue;
+    }
+
+    const name = TAG_ALIASES[tag.name] ?? tag.name;
+    if (!ALLOWED_TAGS.has(name)) continue;
+
+    if (tag.closing) {
+      if (!VOID_TAGS.has(name)) closeTo(name);
+      continue;
+    }
+    if (VOID_TAGS.has(name)) {
+      out.push("<br>");
+      continue;
+    }
+    if (name === "a") {
+      closeTo("a");
+      const href = tag.attributes.href;
+      if (href !== undefined && isSafeUrl(href)) {
+        out.push(
+          `<a href="${escapeAttribute(decodeEntities(href).trim())}" rel="noopener noreferrer nofollow" target="_blank">`,
+        );
+      } else {
+        out.push("<a>");
+      }
+      stack.push("a");
+      continue;
+    }
+    // Block elements cannot nest inside inline ones or inside paragraphs; close what they would break.
+    if (name === "p" || name === "h2" || name === "h3" || name === "blockquote") {
+      for (const open of ["p", "h2", "h3"]) closeTo(open);
+    }
+    if (name === "li") closeTo("li");
+    out.push(`<${name}>`);
+    stack.push(name);
+  }
+
+  while (stack.length) out.push(`</${stack.pop()}>`);
+  return out.join("").replace(/<a><\/a>/g, "");
+}
+
+/** Plain text of sanitized HTML, used to detect an empty editor. */
+export function htmlToText(html: string): string {
+  return decodeEntities(html.replace(/<br\s*\/?>/gi, "\n").replace(/<[^>]*>/g, "")).trim();
+}

package/src/shell/app-shell/app-shell.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import {
+  createContext,
+  type ReactNode,
+  type RefObject,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
+import { cn } from "../../utils/cn.js";
+
+/** Container width (px) below which the shell is compact: the sidebar becomes a drawer. */
+export const APP_SHELL_BREAKPOINT = 900;
+
+const useIsomorphicLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
+
+/**
+ * Whether the measured width of `resolve(ref.current)` is under the breakpoint. Starts as
+ * `false` (desktop) on the server and for the first client render, then measures before paint.
+ */
+export function useCompactContainer(
+  ref: RefObject<HTMLElement | null>,
+  resolve: (element: HTMLElement) => Element | null = (element) => element,
+  enabled = true,
+): boolean {
+  const [compact, setCompact] = useState(false);
+
+  useIsomorphicLayoutEffect(() => {
+    const element = ref.current ? resolve(ref.current) : null;
+    if (!enabled || !element) return;
+    const measure = () => setCompact(element.getBoundingClientRect().width < APP_SHELL_BREAKPOINT);
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    return () => observer.disconnect();
+  }, [ref, enabled]);
+
+  return compact;
+}
+
+interface AppShellState {
+  compact: boolean;
+}
+
+const AppShellContext = createContext<AppShellState | null>(null);
+
+/** `null` outside an `AppShell`; otherwise whether the shell is narrower than 900 px. */
+export function useAppShell(): AppShellState | null {
+  return useContext(AppShellContext);
+}
+
+export interface AppShellProps {
+  children: ReactNode;
+  className?: string;
+}
+
+/**
+ * Root of the app frame (sidebar + topbar + page). It is the `app` container: the sidebar turns
+ * into a drawer and the topbar shows its menu button when the SHELL is under 900 px wide,
+ * whatever the viewport is, so the same shell works in a full page, a preview or a story.
+ */
+export function AppShell({ children, className }: AppShellProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const compact = useCompactContainer(ref);
+  return (
+    <AppShellContext.Provider value={{ compact }}>
+      <div ref={ref} className={cn("@container/app flex min-w-0", className)}>
+        {children}
+      </div>
+    </AppShellContext.Provider>
+  );
+}

package/src/shell/app-shell/index.ts

@@ -0,0 +1,6 @@
+export {
+  APP_SHELL_BREAKPOINT,
+  AppShell,
+  type AppShellProps,
+  useAppShell,
+} from "./app-shell.js";

package/src/shell/index.ts

@@ -0,0 +1,3 @@
+export * from "./app-shell/index.js";
+export * from "./sidebar/index.js";
+export * from "./topbar/index.js";

package/src/shell/sidebar/index.ts

@@ -0,0 +1,8 @@
+export {
+  Sidebar,
+  type SidebarGroup,
+  type SidebarItem,
+  type SidebarLinkProps,
+  type SidebarProps,
+  type SidebarRenderLink,
+} from "./sidebar.js";

package/src/shell/sidebar/sidebar.tsx

@@ -0,0 +1,172 @@
+"use client";
+
+import { type ReactNode, useEffect, useRef } from "react";
+import { cn } from "../../utils/cn.js";
+import { useAppShell, useCompactContainer } from "../app-shell/app-shell.js";
+
+export interface SidebarLinkProps {
+  href: string;
+  className: string;
+  children: ReactNode;
+  "aria-current"?: "page";
+}
+
+/** Renders a navigation link; inject your router's link component here. */
+export type SidebarRenderLink = (props: SidebarLinkProps) => ReactNode;
+
+export interface SidebarItem {
+  id: string;
+  label: string;
+  href: string;
+  icon?: ReactNode;
+  active?: boolean;
+  /** Short badge content (a count, a status node...). */
+  badge?: ReactNode;
+  badgeTone?: "default" | "danger";
+  /** Screen-reader-only context announced after the badge. */
+  badgeLabel?: string;
+}
+
+export interface SidebarGroup {
+  id: string;
+  label: string;
+  items: SidebarItem[];
+}
+
+export interface SidebarProps {
+  groups: SidebarGroup[];
+  /** Accessible name of the sidebar landmark. */
+  ariaLabel: string;
+  /** Brand block shown at the top. */
+  header?: ReactNode;
+  /** Block pinned to the bottom (e.g. the current user). */
+  footer?: ReactNode;
+  /** Link renderer; defaults to a plain anchor. */
+  renderLink?: SidebarRenderLink;
+  /** Drawer state when the app container is under 900 px. Ignored above it, where the sidebar is always visible. */
+  open?: boolean;
+  onClose?: () => void;
+  className?: string;
+}
+
+const defaultRenderLink: SidebarRenderLink = ({ children, ...props }) => (
+  <a {...props}>{children}</a>
+);
+
+/**
+ * Main navigation. Always visible when its app container is wide; an off-canvas drawer under
+ * 900 px of container width, `inert` while closed so it is not reachable by keyboard.
+ * Render it inside `AppShell`: the container decides, never the viewport. Without an `AppShell`
+ * it measures its parent element instead.
+ */
+export function Sidebar({
+  groups,
+  ariaLabel,
+  header,
+  footer,
+  renderLink = defaultRenderLink,
+  open = false,
+  onClose,
+  className,
+}: SidebarProps) {
+  const shell = useAppShell();
+  const asideRef = useRef<HTMLElement>(null);
+  const parentCompact = useCompactContainer(asideRef, (aside) => aside.parentElement, !shell);
+  const isMobile = shell ? shell.compact : parentCompact;
+  const closedOnMobile = isMobile && !open;
+  const openOnMobile = isMobile && open;
+
+  useEffect(() => {
+    if (!openOnMobile) return;
+    asideRef.current?.querySelector<HTMLElement>("a[href]")?.focus();
+  }, [openOnMobile]);
+
+  useEffect(() => {
+    if (!openOnMobile || !onClose) return;
+    const close = onClose;
+    function onKeyDown(event: KeyboardEvent) {
+      if (event.key === "Escape") close();
+    }
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [openOnMobile, onClose]);
+
+  return (
+    <>
+      <aside
+        ref={asideRef}
+        aria-label={ariaLabel}
+        inert={closedOnMobile || undefined}
+        className={cn(
+          "fixed inset-y-0 left-0 z-45 flex h-screen w-side-width flex-col gap-4.5 overflow-y-auto border-r-divider bg-surface px-3 pt-3.5 pb-3 transition-transform duration-200",
+          // Inside AppShell the container query decides before any script runs (no flash on a
+          // narrow first paint); the measured state only drives inert, the scrim and focus.
+          shell
+            ? cn(
+                open ? "translate-x-0" : "-translate-x-full",
+                "@min-[900px]/app:sticky @min-[900px]/app:top-0 @min-[900px]/app:translate-x-0",
+              )
+            : cn(
+                isMobile ? "fixed" : "sticky top-0",
+                closedOnMobile ? "-translate-x-full" : "translate-x-0",
+              ),
+          openOnMobile && "shadow-overlay",
+          className,
+        )}
+      >
+        {header}
+        {groups.map((group) => (
+          <nav key={group.id} aria-label={group.label} className="flex flex-col gap-px">
+            <div className="px-2.5 pb-1.5 text-overline text-ink-3">{group.label}</div>
+            {group.items.map((item) => {
+              const badgeTone =
+                item.badgeTone === "danger"
+                  ? "bg-danger-soft text-danger"
+                  : "bg-surface-2 text-ink-2";
+              return (
+                <div key={item.id}>
+                  {renderLink({
+                    href: item.href,
+                    "aria-current": item.active ? "page" : undefined,
+                    className: cn(
+                      "flex items-center gap-2.5 rounded-control px-2.5 py-2 text-control text-ink-2 hover:bg-surface-2 hover:text-ink [&_svg]:size-4.25 [&_svg]:shrink-0",
+                      item.active && "bg-accent-soft font-bold text-accent-ink",
+                    ),
+                    children: (
+                      <>
+                        {item.icon}
+                        <span className="min-w-0 truncate">{item.label}</span>
+                        {item.badge !== undefined ? (
+                          <span
+                            className={cn(
+                              "ml-auto shrink-0 rounded-chip px-1.5 py-0.75 text-count",
+                              badgeTone,
+                            )}
+                          >
+                            {item.badge}
+                            {item.badgeLabel ? (
+                              <span className="sr-only"> {item.badgeLabel}</span>
+                            ) : null}
+                          </span>
+                        ) : null}
+                      </>
+                    ),
+                  })}
+                </div>
+              );
+            })}
+          </nav>
+        ))}
+        {footer ? <div className="mt-auto">{footer}</div> : null}
+      </aside>
+      {openOnMobile ? (
+        <div
+          data-sidebar-scrim
+          aria-hidden="true"
+          onClick={onClose}
+          className="fixed inset-0 z-44 bg-scrim"
+        />
+      ) : null}
+    </>
+  );
+}

package/src/shell/topbar/index.ts

@@ -0,0 +1 @@
+export { Topbar, type TopbarProps } from "./topbar.js";

package/src/shell/topbar/topbar.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import { Menu, Search } from "lucide-react";
+import { type ReactNode, type Ref, useEffect, useState } from "react";
+import { cn } from "../../utils/cn.js";
+
+function isApplePlatform(): boolean {
+  if (typeof navigator === "undefined") return false;
+  return /Mac|iPhone|iPod|iPad/.test(navigator.platform || navigator.userAgent || "");
+}
+
+export interface TopbarProps {
+  /** Breadcrumb trail in order; the last entry is the current view. */
+  breadcrumbs: string[];
+  /** Accessible name of the breadcrumb landmark. */
+  breadcrumbsLabel: string;
+  /** Menu button (shown when the `AppShell` container is under 900 px, matching the Sidebar drawer) that opens the sidebar drawer. Needs an `@container/app` ancestor, which `AppShell` provides. Omitted when not set. */
+  onOpenMenu?: () => void;
+  menuLabel?: string;
+  /** Ref to the menu button so the opener can restore focus when the drawer closes. */
+  menuButtonRef?: Ref<HTMLButtonElement>;
+  /** Called by the search trigger and by Cmd/Ctrl+K. */
+  onSearch: () => void;
+  searchLabel: string;
+  searchPlaceholder: string;
+  /** Slot between the search trigger and the end block (status, notifications, primary action). */
+  actions?: ReactNode;
+  /** Slot at the far end (e.g. the account menu). */
+  end?: ReactNode;
+  className?: string;
+}
+
+export function Topbar({
+  breadcrumbs,
+  breadcrumbsLabel,
+  onOpenMenu,
+  menuLabel,
+  menuButtonRef,
+  onSearch,
+  searchLabel,
+  searchPlaceholder,
+  actions,
+  end,
+  className,
+}: TopbarProps) {
+  const [shortcut, setShortcut] = useState("Ctrl+K");
+
+  useEffect(() => {
+    setShortcut(isApplePlatform() ? "⌘K" : "Ctrl+K");
+  }, []);
+
+  useEffect(() => {
+    function onKeyDown(event: KeyboardEvent) {
+      if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== "k") return;
+      event.preventDefault();
+      onSearch();
+    }
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [onSearch]);
+
+  const current = breadcrumbs.at(-1);
+  const previous = breadcrumbs.slice(0, -1);
+
+  return (
+    <header
+      className={cn(
+        "@container/topbar sticky top-0 z-30 h-top-height border-b-divider bg-bg",
+        className,
+      )}
+    >
+      <div className="flex h-full min-w-0 items-center gap-2.5 px-4 @min-[640px]/topbar:px-7">
+        {onOpenMenu ? (
+          <button
+            ref={menuButtonRef}
+            type="button"
+            aria-label={menuLabel}
+            onClick={onOpenMenu}
+            className="hidden size-8.5 shrink-0 items-center justify-center rounded-control text-ink-2 hover:bg-surface-2 hover:text-ink @max-[900px]/app:inline-flex"
+          >
+            <Menu className="size-5" aria-hidden="true" />
+          </button>
+        ) : null}
+
+        <nav
+          aria-label={breadcrumbsLabel}
+          className="flex min-w-0 shrink items-center gap-2 whitespace-nowrap text-ink-3 text-meta"
+        >
+          {previous.map((crumb) => (
+            <span key={crumb} className="flex items-center gap-2 @max-[560px]/topbar:hidden">
+              <span>{crumb}</span>
+              <span aria-hidden="true" className="text-line-control">
+                /
+              </span>
+            </span>
+          ))}
+          <strong aria-current="page" className="min-w-0 truncate font-semibold text-ink">
+            {current}
+          </strong>
+        </nav>
+
+        <button
+          type="button"
+          aria-label={searchLabel}
+          onClick={onSearch}
+          className="ml-auto flex h-8.5 w-[min(320px,38cqw)] shrink-0 items-center gap-2 rounded-input border-control bg-surface-control pr-2 pl-2.5 text-ink-3 text-meta @max-[700px]/topbar:w-8.5 @max-[700px]/topbar:justify-center @max-[700px]/topbar:px-0"
+        >
+          <Search className="size-4 shrink-0" aria-hidden="true" />
+          <span className="truncate @max-[700px]/topbar:hidden">{searchPlaceholder}</span>
+          <span className="ml-auto rounded-xs border-divider bg-surface-2 px-1.25 py-0.5 font-mono text-count text-ink-2 @max-[700px]/topbar:hidden">
+            {shortcut}
+          </span>
+        </button>
+
+        {actions}
+        {end}
+      </div>
+    </header>
+  );
+}