@kahitsan/ksui 0.5.0 → 0.7.0

package/src/components/base/SectionHeading.tsx

@@ -0,0 +1,100 @@
+import { Show, type JSX } from "solid-js";
+
+/** Horizontal alignment for the whole heading block. */
+export type SectionHeadingAlign = "left" | "center" | "right";
+
+/** Heading level rendered for the title element. */
+export type SectionHeadingLevel = "h1" | "h2" | "h3";
+
+export interface SectionHeadingProps {
+  /**
+   * Title content. Accept JSX so a caller can apply its own brand styling
+   * (e.g. a gradient span) on part of the title without this component
+   * carrying any site-specific CSS.
+   */
+  title: JSX.Element;
+  /** Small uppercase, wide-tracked label above the title (the "eyebrow"). */
+  kicker?: string;
+  /** Supporting copy below the title. Accepts JSX for richer content. */
+  subtitle?: JSX.Element;
+  /**
+   * Show a short underline accent bar below the title. The bar inherits the
+   * accent color; override with `accentClass`.
+   */
+  accent?: boolean;
+  /** Tailwind class controlling the accent bar color. */
+  accentClass?: string;
+  /** Tailwind class controlling the kicker color. */
+  kickerClass?: string;
+  /** Tailwind class controlling the title color. */
+  titleClass?: string;
+  /** Tailwind class controlling the subtitle color. */
+  subtitleClass?: string;
+  /** Block alignment. Defaults to "left". */
+  align?: SectionHeadingAlign;
+  /** Title element tag. Defaults to "h2". */
+  as?: SectionHeadingLevel;
+  /** Extra classes on the outer wrapper. */
+  class?: string;
+}
+
+const ALIGN_WRAP: Record<SectionHeadingAlign, string> = {
+  left: "text-left items-start",
+  center: "text-center items-center",
+  right: "text-right items-end",
+};
+
+// Per-level title sizing. Domain-free defaults; callers override via titleClass.
+const TITLE_SIZE: Record<SectionHeadingLevel, string> = {
+  h1: "text-3xl md:text-4xl lg:text-6xl font-bold tracking-tight",
+  h2: "text-2xl md:text-3xl lg:text-4xl font-bold",
+  h3: "text-xl md:text-2xl font-bold",
+};
+
+/**
+ * A recurring section header block: an optional uppercase kicker, a title
+ * (any JSX, so the caller can apply brand-specific styling), an optional
+ * underline accent bar, and optional subtitle copy.
+ *
+ * Presentational only. No site copy, no domain coupling — every piece of text
+ * and color comes from props.
+ */
+export default function SectionHeading(props: SectionHeadingProps): JSX.Element {
+  const align = () => props.align ?? "left";
+  const level = () => props.as ?? "h2";
+
+  const Title = (titleProps: { class: string; children: JSX.Element }): JSX.Element => {
+    const tag = level();
+    if (tag === "h1") return <h1 class={titleProps.class}>{titleProps.children}</h1>;
+    if (tag === "h3") return <h3 class={titleProps.class}>{titleProps.children}</h3>;
+    return <h2 class={titleProps.class}>{titleProps.children}</h2>;
+  };
+
+  return (
+    <div class={`flex flex-col ${ALIGN_WRAP[align()]} ${props.class ?? ""}`}>
+      <Show when={props.kicker}>
+        <div
+          class={`text-xs font-bold tracking-[0.3em] uppercase mb-2 ${
+            props.kickerClass ?? "text-amber-500"
+          }`}
+        >
+          {props.kicker}
+        </div>
+      </Show>
+
+      <Title class={`${TITLE_SIZE[level()]} ${props.titleClass ?? "text-white"}`}>
+        {props.title}
+      </Title>
+
+      <Show when={props.accent}>
+        <div class={`w-20 h-1 mt-4 rounded-full ${props.accentClass ?? "bg-amber-500"}`} />
+      </Show>
+
+      <Show when={props.subtitle}>
+        <p class={`mt-4 text-base md:text-lg max-w-2xl ${props.subtitleClass ?? "text-zinc-400"}`}>
+          {props.subtitle}
+        </p>
+      </Show>
+    </div>
+  );
+}

package/src/components/base/SocialLinksBar.tsx

@@ -0,0 +1,92 @@
+import { For, type Component, type JSX } from "solid-js";
+
+/** Icon component shape: any component that accepts a numeric `size`
+ *  (lucide-solid icons satisfy this, as does any custom SVG component). */
+export type SocialIcon = Component<{ size?: number }>;
+
+export interface SocialLink {
+  /** Destination URL. Opened in a new tab with rel="noopener noreferrer". */
+  href: string;
+  /** Icon component rendered inside the button (e.g. a lucide-solid icon). */
+  icon: SocialIcon;
+  /** Accessible label, used for `aria-label` and `title`. */
+  label: string;
+}
+
+/** Button outline shape. `round` is a full circle; `clip` cuts the
+ *  top-right corner with a clip-path (the angular brand variant). */
+export type SocialLinksShape = "round" | "clip";
+
+export interface SocialLinksBarProps {
+  /** The links to render. The caller owns the URLs and icons; nothing
+   *  domain-specific lives in the component. */
+  links: SocialLink[];
+  /** Button outline shape. Defaults to `round`. */
+  shape?: SocialLinksShape;
+  /** Pixel size of each square button. Defaults to 40 (`clip` defaults to 48). */
+  buttonSize?: number;
+  /** Pixel size of the icon. Defaults to ~45% of the button size. */
+  iconSize?: number;
+  /** Extra classes on the wrapping `<nav>`. */
+  class?: string;
+  testId?: string;
+}
+
+// Runtime-injected clip-path utility. ksui ships no sidecar CSS (the package
+// exports only ./src), so the one rule the `clip` shape needs is emitted once
+// as a <style> tag rather than imported from a sibling .css file.
+const CLIP_STYLE_ID = "ksui-social-clip-style";
+const CLIP_STYLE = `.ksui-social-clip{clip-path:polygon(0 0,calc(100% - 8px) 0,100% 8px,100% 100%,0 100%);}`;
+
+// Inject the clip-path rule once per document, matching the SSR-safe
+// getElementById-dedupe pattern used by Button/ThemeToggle. A module-level
+// boolean would be non-reentrant across SSR requests (the worker reuses the
+// module), so the style must be keyed off the document, not module state.
+function ensureSocialClipStyle(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(CLIP_STYLE_ID)) return;
+  const el = document.createElement("style");
+  el.id = CLIP_STYLE_ID;
+  el.textContent = CLIP_STYLE;
+  document.head.appendChild(el);
+}
+
+/**
+ * A horizontal row of accessible, round (or clip-cornered) icon buttons that
+ * link out to external profiles. Each button opens its href in a new tab with
+ * a safe `rel`, carries an `aria-label`, and renders the caller-supplied icon.
+ *
+ * Domain-free: the specific URLs, icons, and labels all come from `links`.
+ */
+export default function SocialLinksBar(props: SocialLinksBarProps): JSX.Element {
+  ensureSocialClipStyle();
+  const shape = () => props.shape ?? "round";
+  const btn = () => props.buttonSize ?? (shape() === "clip" ? 48 : 40);
+  const icon = () => props.iconSize ?? Math.round(btn() * 0.45);
+  const shapeClass = () =>
+    shape() === "clip" ? "ksui-social-clip" : "rounded-full";
+
+  return (
+    <nav
+      data-testid={props.testId}
+      class={`flex gap-4 ${props.class ?? ""}`}
+      aria-label="Social links"
+    >
+      <For each={props.links}>
+        {(link) => (
+          <a
+            href={link.href}
+            target="_blank"
+            rel="noopener noreferrer"
+            title={link.label}
+            aria-label={link.label}
+            class={`flex items-center justify-center bg-zinc-800 text-zinc-400 transition-all hover:bg-amber-500 hover:text-black ${shapeClass()}`}
+            style={{ width: `${btn()}px`, height: `${btn()}px` }}
+          >
+            {link.icon({ size: icon() })}
+          </a>
+        )}
+      </For>
+    </nav>
+  );
+}

package/src/components/base/StatusIndicator.tsx

@@ -0,0 +1,110 @@
+import { Show, type JSX } from "solid-js";
+
+export type StatusIndicatorTone = "success" | "neutral" | "warning" | "danger" | "info";
+
+interface ToneClass {
+  /** Filled dot color. */
+  dot: string;
+  /** Label text color. */
+  text: string;
+  /** Box-shadow glow used when the dot pulses (an arbitrary Tailwind value). */
+  glow: string;
+}
+
+// Module-private tone palette. The caller maps its own availability/state
+// (online/offline, open/closed, healthy/degraded) to one of these tones and
+// passes a plain label; nothing domain-specific leaks into this atom.
+const TONE_CLASS: Record<StatusIndicatorTone, ToneClass> = {
+  success: {
+    dot: "bg-emerald-400",
+    text: "text-white",
+    glow: "shadow-[0_0_10px_rgba(52,211,153,0.6)]",
+  },
+  neutral: {
+    dot: "bg-zinc-400",
+    text: "text-zinc-400",
+    glow: "shadow-[0_0_10px_rgba(161,161,170,0.5)]",
+  },
+  warning: {
+    dot: "bg-amber-400",
+    text: "text-amber-300",
+    glow: "shadow-[0_0_10px_rgba(251,191,36,0.6)]",
+  },
+  danger: {
+    dot: "bg-red-400",
+    text: "text-red-300",
+    glow: "shadow-[0_0_10px_rgba(248,113,113,0.6)]",
+  },
+  info: {
+    dot: "bg-blue-400",
+    text: "text-blue-300",
+    glow: "shadow-[0_0_10px_rgba(96,165,250,0.6)]",
+  },
+};
+
+export interface StatusIndicatorProps {
+  /** Text shown beside the dot (the caller's own label). */
+  label: string;
+  /** Domain-free tone selector. The caller maps its enum to one of these. */
+  tone?: StatusIndicatorTone;
+  /**
+   * Convenience boolean: when provided, overrides `tone` with `success` (true)
+   * or `danger` (false). Lets a caller bind a plain availability flag.
+   */
+  online?: boolean;
+  /** Animate the dot with a pulse + glow (good for a "live" indicator). */
+  pulse?: boolean;
+  /** Render the label uppercase with wide tracking (the marquee/chip style). */
+  uppercase?: boolean;
+  /** Optional small caption above the label (e.g. a category line). */
+  caption?: string;
+  /** Caption text color class; defaults to an amber accent. */
+  captionClass?: string;
+  /** Extra classes on the wrapper. */
+  class?: string;
+  testId?: string;
+}
+
+// Single availability-indicator atom. A filled, optionally pulsing colored dot
+// next to a label. Distinct from StatusPill (a bordered tinted text chip) — this
+// is the animated "live status" dot. The caller owns the domain → tone mapping
+// and the label text.
+export default function StatusIndicator(props: StatusIndicatorProps): JSX.Element {
+  const tone = (): StatusIndicatorTone =>
+    props.online === undefined ? (props.tone ?? "neutral") : props.online ? "success" : "danger";
+  const tc = () => TONE_CLASS[tone()];
+
+  return (
+    <div
+      data-testid={props.testId}
+      class={`flex items-center gap-3 ${props.class ?? ""}`}
+    >
+      <span
+        aria-hidden="true"
+        class={`h-3 w-3 shrink-0 rounded-full ${tc().dot} ${
+          props.pulse ? `animate-pulse ${tc().glow}` : ""
+        }`}
+      />
+      <div>
+        <Show when={props.caption}>
+          <div
+            class={`text-xs font-bold uppercase tracking-widest ${
+              props.captionClass ?? "text-amber-400"
+            }`}
+          >
+            {props.caption}
+          </div>
+        </Show>
+        <div
+          class={`${tc().text} ${
+            props.uppercase
+              ? "text-xs font-bold uppercase tracking-widest"
+              : "text-sm font-bold"
+          }`}
+        >
+          {props.label}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/components/base/ThemeToggle.tsx

@@ -0,0 +1,112 @@
+// Source: kahitsan-web src/components/Header.tsx (ThemeToggle, lines 30-45)
+// + its CSS in src/assets/css/button.css (.ks-theme-toggle*).
+// Extracted as a domain-free, controlled primitive: the theme state is lifted
+// to props (`value` + `onToggle`) so it carries no dependency on kahitsan's
+// ~/lib/theme. Only solid-js + lucide-solid.
+//
+// ksui ships no sibling .css and no sidecar CSS in the published package, so
+// the custom track/thumb/icon styles (transitions, the sliding ::after thumb)
+// are injected once at runtime via a <style> tag — the same pattern ProgressBar
+// uses — and referenced by plain, unscoped class names.
+
+import type { JSX } from "solid-js";
+import { splitProps } from "solid-js";
+import Sun from "lucide-solid/icons/sun";
+import Moon from "lucide-solid/icons/moon";
+
+const THEME_TOGGLE_STYLE_ID = "ks-theme-toggle-inline-style";
+const THEME_TOGGLE_CSS = `
+.ks-theme-toggle { background: none; border: none; padding: 2px; cursor: pointer; display: flex; align-items: center; }
+.ks-theme-toggle-track { position: relative; display: flex; align-items: center; justify-content: space-between; width: 52px; height: 28px; border-radius: 14px; background-color: #3f3f46; padding: 0 2px; transition: background-color 0.3s ease; }
+.ks-theme-toggle-track[data-active] { background-color: #d3c5ac; }
+.ks-theme-toggle-icon { position: relative; z-index: 2; display: flex; align-items: center; justify-content: center; width: 24px; height: 24px; border-radius: 50%; pointer-events: none; transition: color 0.3s ease; }
+.ks-theme-toggle-track::after { content: ''; position: absolute; left: 2px; top: 2px; width: 24px; height: 24px; border-radius: 50%; background-color: #52525b; box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3); transition: transform 0.3s ease, background-color 0.3s ease; z-index: 1; }
+.ks-theme-toggle-track[data-active]::after { transform: translateX(24px); background-color: #ffffff; box-shadow: 0 1px 3px rgba(0, 0, 0, 0.15); }
+.ks-theme-toggle-icon-moon { color: #fbbf24; }
+.ks-theme-toggle-icon-sun { color: rgba(255, 255, 255, 0.3); }
+.ks-theme-toggle-track[data-active] .ks-theme-toggle-icon-moon { color: rgba(120, 90, 0, 0.3); }
+.ks-theme-toggle-track[data-active] .ks-theme-toggle-icon-sun { color: #785a00; }
+.ks-theme-toggle:hover .ks-theme-toggle-track { background-color: #52525b; }
+.ks-theme-toggle:hover .ks-theme-toggle-track[data-active] { background-color: #c9b99a; }
+@media (prefers-reduced-motion: reduce) { .ks-theme-toggle-track, .ks-theme-toggle-track::after, .ks-theme-toggle-icon { transition: none; } }
+`;
+
+function ensureThemeToggleStyle(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(THEME_TOGGLE_STYLE_ID)) return;
+  const el = document.createElement("style");
+  el.id = THEME_TOGGLE_STYLE_ID;
+  el.textContent = THEME_TOGGLE_CSS;
+  document.head.appendChild(el);
+}
+
+export type ThemeToggleValue = "dark" | "light";
+
+export interface ThemeToggleProps
+  extends Omit<JSX.ButtonHTMLAttributes<HTMLButtonElement>, "value" | "onToggle"> {
+  /** Current theme. `"light"` slides the thumb right and activates the sun. */
+  value: ThemeToggleValue;
+  /** Called with the opposite theme when the toggle is clicked. */
+  onToggle: (next: ThemeToggleValue) => void;
+  /**
+   * Accessible label. Receives the theme the click will switch TO so the
+   * default reads e.g. "Switch to light mode". Override for non-English UIs.
+   */
+  ariaLabel?: (next: ThemeToggleValue) => string;
+  /** Optional test hook (data-testid). */
+  testId?: string;
+}
+
+function cn(...classes: Array<string | undefined | null | false>): string {
+  return classes.filter(Boolean).join(" ");
+}
+
+const defaultAriaLabel = (next: ThemeToggleValue): string => `Switch to ${next} mode`;
+
+/**
+ * A controlled sliding sun/moon track toggle. Domain-free: it owns no theme
+ * state and applies no theme — it renders `value` and reports the intended
+ * next value through `onToggle`. The parent owns the theme source of truth.
+ */
+export default function ThemeToggle(props: ThemeToggleProps): JSX.Element {
+  ensureThemeToggleStyle();
+
+  const [local, rest] = splitProps(props, [
+    "value",
+    "onToggle",
+    "ariaLabel",
+    "testId",
+    "class",
+    "onClick",
+  ]);
+
+  const isLight = (): boolean => local.value === "light";
+  const next = (): ThemeToggleValue => (isLight() ? "dark" : "light");
+  const label = (): string => (local.ariaLabel ?? defaultAriaLabel)(next());
+
+  const handleClick: JSX.EventHandler<HTMLButtonElement, MouseEvent> = (event) => {
+    local.onToggle(next());
+    if (typeof local.onClick === "function") local.onClick(event);
+  };
+
+  return (
+    <button
+      type="button"
+      class={cn("ks-theme-toggle", local.class)}
+      aria-label={label()}
+      title={label()}
+      data-testid={local.testId}
+      onClick={handleClick}
+      {...rest}
+    >
+      <span class="ks-theme-toggle-track" data-active={isLight() ? "" : undefined}>
+        <span class="ks-theme-toggle-icon ks-theme-toggle-icon-moon">
+          <Moon size={12} />
+        </span>
+        <span class="ks-theme-toggle-icon ks-theme-toggle-icon-sun">
+          <Sun size={12} />
+        </span>
+      </span>
+    </button>
+  );
+}

package/src/components/composite/NotFound.tsx

@@ -0,0 +1,130 @@
+// Centered 404 / empty-state panel: an optional logo slot, a large display
+// title, a heading, a message, and a default "go back" action button. It is a
+// fully prop-driven, domain-free primitive — every piece of copy defaults to a
+// generic 404 string but is overridable, and nothing about any specific site
+// is hard-coded.
+//
+// Unlike the host-owned Button, this is a standalone primitive: it imports only
+// solid-js and lucide-solid, never `@kserp/host-ui` or a router. The default
+// action renders a plain, self-styled button. Navigation is left to the caller
+// via `onButtonClick` (or `href`, which renders an anchor instead). Callers who
+// want the host Button can pass it through the `action` slot, which fully
+// replaces the built-in button.
+
+import type { JSX } from "solid-js";
+import { Show, splitProps } from "solid-js";
+import { ArrowLeft } from "lucide-solid";
+
+export interface NotFoundProps
+  extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "title"> {
+  /** Large display title. Defaults to "404". Pass "" to hide it entirely. */
+  title?: string;
+  /** Secondary heading under the title. Defaults to "Page Not Found". */
+  heading?: string;
+  /** Supporting message under the heading. */
+  message?: string;
+  /** Label for the default action button. Defaults to "Go Back Home". */
+  buttonText?: string;
+  /**
+   * When set, the default action renders as an anchor pointing here instead of
+   * a button. Ignored when `onButtonClick` or `action` is provided.
+   */
+  href?: string;
+  /** Click handler for the default action button. */
+  onButtonClick?: () => void;
+  /** Optional element rendered above the title (e.g. a logo or icon). */
+  logo?: JSX.Element;
+  /** Hide the action entirely. */
+  hideButton?: boolean;
+  /**
+   * Replace the built-in action with a custom element (e.g. the host Button).
+   * When provided, `buttonText`, `href`, and `onButtonClick` are ignored.
+   */
+  action?: JSX.Element;
+  /** Test id applied to the outer container. */
+  testId?: string;
+}
+
+export default function NotFound(props: NotFoundProps): JSX.Element {
+  const [local, others] = splitProps(props, [
+    "title",
+    "heading",
+    "message",
+    "buttonText",
+    "href",
+    "onButtonClick",
+    "logo",
+    "hideButton",
+    "action",
+    "testId",
+    "class",
+  ]);
+
+  const showTitle = () => local.title !== "";
+  const buttonClass =
+    "inline-flex items-center justify-center gap-2 rounded-md border " +
+    "border-amber-600/60 bg-amber-600/20 px-5 py-2.5 text-sm font-semibold " +
+    "text-amber-400 transition-colors hover:border-amber-500 " +
+    "hover:bg-amber-600/30 focus:outline-none focus-visible:ring-2 " +
+    "focus-visible:ring-amber-500/60";
+
+  return (
+    <div
+      class={
+        "flex items-center justify-center min-h-screen" +
+        (local.class ? " " + local.class : "")
+      }
+      data-testid={local.testId}
+      {...others}
+    >
+      <div class="text-center">
+        <Show when={local.logo}>
+          <div class="flex items-center justify-center mx-auto mb-6">{local.logo}</div>
+        </Show>
+
+        <Show when={showTitle()}>
+          <h1 class="text-4xl md:text-6xl font-bold text-amber-500 mb-4">
+            {local.title || "404"}
+          </h1>
+        </Show>
+
+        <h2 class="text-xl md:text-2xl font-bold text-white mb-3">
+          {local.heading || "Page Not Found"}
+        </h2>
+
+        <p class="text-sm text-zinc-400 max-w-md mb-8">
+          {local.message ||
+            "The page you're looking for doesn't exist or has been moved."}
+        </p>
+
+        <Show when={!local.hideButton}>
+          <Show
+            when={local.action}
+            fallback={
+              <Show
+                when={local.href && !local.onButtonClick}
+                fallback={
+                  <button
+                    type="button"
+                    class={buttonClass}
+                    onClick={() => local.onButtonClick?.()}
+                  >
+                    <ArrowLeft size={16} aria-hidden="true" />
+                    {local.buttonText || "Go Back Home"}
+                  </button>
+                }
+              >
+                <a href={local.href} class={buttonClass}>
+                  <ArrowLeft size={16} aria-hidden="true" />
+                  {local.buttonText || "Go Back Home"}
+                </a>
+              </Show>
+            }
+          >
+            {local.action}
+          </Show>
+        </Show>
+      </div>
+    </div>
+  );
+}