@reddb-io/ui-kit 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reddb-io/ui-kit",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "private": false,
   "description": "Low-level RedDB UI design-system primitives.",
   "type": "module",

package/src/lib/EmptyState.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+  // The "live or empty — never fake" fallback: a centered icon + title +
+  // optional description, with an optional `action` slot (a fix command, a
+  // primary button). Used when a list has no rows or a surface is unreachable.
+  import type { Snippet } from 'svelte'
+
+  interface Props {
+    title: string
+    description?: string
+    /** Leading icon, rendered muted above the title. */
+    icon?: Snippet
+    /** Optional call to action beneath the copy. */
+    action?: Snippet
+    class?: string
+  }
+  let { title, description, icon, action, class: klass = '' }: Props = $props()
+</script>
+
+<div class="flex flex-col items-center justify-center gap-2 px-6 py-10 text-center {klass}">
+  {#if icon}
+    <span class="flex size-8 items-center justify-center text-fg-3">{@render icon()}</span>
+  {/if}
+  <p class="text-[13px] text-fg-1">{title}</p>
+  {#if description}
+    <p class="max-w-prose text-[12px] leading-relaxed text-fg-2">{description}</p>
+  {/if}
+  {#if action}
+    <div class="mt-2">{@render action()}</div>
+  {/if}
+</div>

package/src/lib/ListRow.svelte

@@ -0,0 +1,67 @@
+<script lang="ts">
+  // A settings/governance row: a `title` (+ optional `description` and a mono
+  // `hint`) on the left, a right-aligned `action` slot, and an optional `below`
+  // slot that spans the row's full width (for inline editors, diffs, warnings).
+  //
+  // `wide` flips the layout to a stacked variant: the label block sits on top
+  // and the action drops to its own full-width line beneath — for actions that
+  // are too large to sit inline (a long input, a segmented control).
+  import type { Snippet } from 'svelte'
+
+  interface Props {
+    title: string
+    /** Secondary line under the title. */
+    description?: string
+    /** Mono hint — a value, key, or id rendered in the data typeface. */
+    hint?: string
+    /** Right-aligned (inline) or full-width-below (wide) action. */
+    action?: Snippet
+    /** Full-width content beneath the row — editors, diffs, warnings. */
+    below?: Snippet
+    /** Stack the action beneath the label block instead of inline-right. */
+    wide?: boolean
+    class?: string
+  }
+  let {
+    title,
+    description,
+    hint,
+    action,
+    below,
+    wide = false,
+    class: klass = '',
+  }: Props = $props()
+</script>
+
+<div
+  data-wide={wide ? '' : undefined}
+  class={[
+    'px-3 py-2.5',
+    wide ? 'flex flex-col gap-2' : 'flex items-center gap-3',
+    klass,
+  ].join(' ')}
+>
+  <div class={['flex min-w-0 items-baseline gap-2', wide ? '' : 'flex-1'].join(' ')}>
+    <div class="min-w-0">
+      <div class="flex items-baseline gap-2">
+        <span class="truncate text-[13px] text-fg-0">{title}</span>
+        {#if hint}
+          <span class="shrink-0 font-mono text-[11px] text-fg-2">{hint}</span>
+        {/if}
+      </div>
+      {#if description}
+        <p class="mt-0.5 text-[12px] leading-snug text-fg-2">{description}</p>
+      {/if}
+    </div>
+  </div>
+
+  {#if action}
+    <div class={['flex items-center gap-2', wide ? 'w-full' : 'shrink-0'].join(' ')}>
+      {@render action()}
+    </div>
+  {/if}
+
+  {#if below}
+    <div class="w-full">{@render below()}</div>
+  {/if}
+</div>

package/src/lib/LoadingState.svelte

@@ -0,0 +1,20 @@
+<script lang="ts">
+  // A quiet inline loading affordance — a spinning ring + optional label.
+  // Honors `prefers-reduced-motion` (the spin is dropped when the user asks for
+  // reduced motion). Pair with a surface while its data is in flight.
+  interface Props {
+    label?: string
+    class?: string
+  }
+  let { label = 'Loading…', class: klass = '' }: Props = $props()
+</script>
+
+<div class="flex items-center justify-center gap-2 px-6 py-10 text-fg-2 {klass}">
+  <span
+    class="size-3.5 rounded-full border-2 border-line-2 border-t-fg-2 motion-safe:animate-spin"
+    aria-hidden="true"
+  ></span>
+  {#if label}
+    <span class="text-[12px]">{label}</span>
+  {/if}
+</div>

package/src/lib/NavItem.svelte

@@ -0,0 +1,53 @@
+<script lang="ts">
+  // A navigation entry for the SplitView nav pane: leading icon + label, an
+  // active state (accent-marked, `aria-current="page"`), and an optional
+  // trailing slot (a count Pill, a chevron). Renders as an `<a>` when `href` is
+  // given, otherwise a `<button>` — so it works for both routing and local
+  // section state.
+  import type { Snippet } from 'svelte'
+
+  interface Props {
+    label: string
+    icon?: Snippet
+    trailing?: Snippet
+    active?: boolean
+    href?: string
+    onclick?: (e: MouseEvent) => void
+    class?: string
+  }
+  let {
+    label,
+    icon,
+    trailing,
+    active = false,
+    href,
+    onclick,
+    class: klass = '',
+  }: Props = $props()
+
+  const cls = $derived(
+    [
+      'inline-flex w-full items-center gap-2 rounded-md px-2 py-1.5 text-left text-[13px] transition-colors',
+      active ? 'bg-bg-2 text-fg-0' : 'text-fg-2 hover:bg-bg-2 hover:text-fg-0',
+      klass,
+    ].join(' '),
+  )
+</script>
+
+{#if href}
+  <a {href} {onclick} aria-current={active ? 'page' : undefined} class={cls}>
+    {#if icon}
+      <span class="flex size-3.5 shrink-0 items-center justify-center">{@render icon()}</span>
+    {/if}
+    <span class="flex-1 truncate">{label}</span>
+    {#if trailing}<span class="shrink-0">{@render trailing()}</span>{/if}
+  </a>
+{:else}
+  <button type="button" {onclick} aria-current={active ? 'page' : undefined} class={cls}>
+    {#if icon}
+      <span class="flex size-3.5 shrink-0 items-center justify-center">{@render icon()}</span>
+    {/if}
+    <span class="flex-1 truncate">{label}</span>
+    {#if trailing}<span class="shrink-0">{@render trailing()}</span>{/if}
+  </button>
+{/if}

package/src/lib/Pill.svelte

@@ -0,0 +1,28 @@
+<script lang="ts" module>
+  import { tv } from 'tailwind-variants'
+  // A small meta chip for counts/labels next to a heading — quieter than Badge
+  // (no uppercase/tracking), tuned for inline use beside a SectionHeading.
+  export const pill = tv({
+    base:
+      'inline-flex items-center gap-1 px-1.5 h-[18px] rounded-full text-[11px] ' +
+      'font-mono leading-none border',
+    variants: {
+      tone: {
+        muted: 'bg-bg-2 text-fg-2 border-line-2',
+        accent: 'bg-accent/15 text-accent border-accent/30',
+      },
+    },
+    defaultVariants: { tone: 'muted' },
+  })
+</script>
+
+<script lang="ts">
+  interface Props {
+    tone?: 'muted' | 'accent'
+    class?: string
+    children?: import('svelte').Snippet
+  }
+  let { tone = 'muted', class: klass = '', children }: Props = $props()
+</script>
+
+<span class={pill({ tone, class: klass })}>{@render children?.()}</span>

package/src/lib/SectionHeading.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+  // A section title row: optional leading icon + title + optional trailing meta
+  // (typically a `Pill` count). Density-first — sits above a stack of ListRows.
+  import type { Snippet } from 'svelte'
+
+  interface Props {
+    title: string
+    /** Leading icon (e.g. a lucide component rendered in a snippet). */
+    icon?: Snippet
+    /** Trailing meta — usually a `Pill` with a count. */
+    meta?: Snippet
+    class?: string
+  }
+  let { title, icon, meta, class: klass = '' }: Props = $props()
+</script>
+
+<div class="flex items-center gap-2 {klass}">
+  {#if icon}
+    <span class="flex size-4 shrink-0 items-center justify-center text-fg-2">{@render icon()}</span>
+  {/if}
+  <h2 class="text-[11px] font-mono uppercase tracking-[0.1em] text-fg-2">{title}</h2>
+  {#if meta}
+    <span class="ml-0.5">{@render meta()}</span>
+  {/if}
+</div>

package/src/lib/SplitView.svelte

@@ -0,0 +1,145 @@
+<script lang="ts" module>
+  // Re-export the pure helpers so consumers can reach them from the same entry
+  // as the component (e.g. to share the breakpoint or the shortcut predicate).
+  export { splitViewGridClass, isSearchShortcut, SPLIT_VIEW_BREAKPOINT_REM } from './split-view'
+</script>
+
+<script lang="ts">
+  // A presentational two-pane shell — `nav | content` at `13rem | minmax(0,1fr)`,
+  // collapsing to a single column on a narrow *container* (not just viewport).
+  // It owns no routing and no domain concepts (ADR-0001): which section is
+  // active is the host's business, driven through these slots. Styling stays in
+  // Tailwind class strings and every region exposes a `*Class` override hook.
+  import type { Snippet } from 'svelte'
+  import { onMount, tick } from 'svelte'
+  import { isSearchShortcut, splitViewGridClass } from './split-view'
+
+  interface Props {
+    /** Left navigation pane content. */
+    nav?: Snippet
+    /** Right content pane. */
+    content?: Snippet
+    /** Pinned to the bottom of the nav pane. */
+    footer?: Snippet
+    /** Focusable search affordance — inline at the top of the nav by default. */
+    search?: Snippet
+    /**
+     * Force a single column (`true`) or two columns (`false`). Omit for the
+     * responsive default (collapses below the container breakpoint).
+     */
+    collapsed?: boolean
+    /** Render the search slot as a centered overlay instead of inline. */
+    searchOverlay?: boolean
+    /** Bindable open state for the search overlay. */
+    searchOpen?: boolean
+    /**
+     * Predicate for the keyboard idiom that focuses (inline) or toggles
+     * (overlay) the search. Defaults to ⌘K / Ctrl+K. Pass `null` to disable —
+     * e.g. when the host already owns ⌘K for a global command palette.
+     */
+    searchShortcut?: ((e: KeyboardEvent) => boolean) | null
+    /** Styling hooks. */
+    class?: string
+    navClass?: string
+    contentClass?: string
+    footerClass?: string
+    searchClass?: string
+  }
+
+  let {
+    nav,
+    content,
+    footer,
+    search,
+    collapsed,
+    searchOverlay = false,
+    searchOpen = $bindable(false),
+    searchShortcut = isSearchShortcut,
+    class: klass = '',
+    navClass = '',
+    contentClass = '',
+    footerClass = '',
+    searchClass = '',
+  }: Props = $props()
+
+  const gridClass = $derived(splitViewGridClass(collapsed))
+
+  let searchHost = $state<HTMLElement>()
+  let overlayHost = $state<HTMLElement>()
+
+  function focusFirst(host: HTMLElement | undefined) {
+    const el = host?.querySelector<HTMLElement>(
+      'input, textarea, select, button, [href], [tabindex]:not([tabindex="-1"])',
+    )
+    el?.focus()
+  }
+
+  async function activateSearch() {
+    if (searchOverlay) {
+      searchOpen = true
+      await tick()
+      focusFirst(overlayHost)
+    } else {
+      focusFirst(searchHost)
+    }
+  }
+
+  onMount(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (searchShortcut && searchShortcut(e)) {
+        e.preventDefault()
+        void activateSearch()
+        return
+      }
+      // Esc closes the overlay regardless of whether the shortcut is enabled.
+      if (searchOverlay && searchOpen && e.key === 'Escape') {
+        e.preventDefault()
+        searchOpen = false
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  })
+</script>
+
+<div class="@container relative h-full min-h-0 w-full {klass}">
+  <div class="grid h-full min-h-0 {gridClass}">
+    <aside
+      class="flex min-h-0 flex-col border-line-1 bg-bg-1 border-b @min-[52rem]:border-b-0 @min-[52rem]:border-r {navClass}"
+    >
+      {#if search && !searchOverlay}
+        <div bind:this={searchHost} class="shrink-0 border-b border-line-1 p-2 {searchClass}">
+          {@render search()}
+        </div>
+      {/if}
+      <div class="min-h-0 flex-1 overflow-y-auto">
+        {@render nav?.()}
+      </div>
+      {#if footer}
+        <div class="mt-auto shrink-0 border-t border-line-1 {footerClass}">
+          {@render footer()}
+        </div>
+      {/if}
+    </aside>
+
+    <section class="min-h-0 min-w-0 overflow-auto bg-bg-0 {contentClass}">
+      {@render content?.()}
+    </section>
+  </div>
+
+  {#if search && searchOverlay && searchOpen}
+    <div
+      class="absolute inset-0 z-40 bg-black/50 backdrop-blur-sm"
+      role="presentation"
+      onclick={() => (searchOpen = false)}
+    ></div>
+    <div
+      bind:this={overlayHost}
+      class="absolute left-1/2 top-[15%] z-50 w-[min(36rem,92%)] -translate-x-1/2 rounded-lg border border-line-2 bg-bg-1 shadow-[var(--shadow-lg)] {searchClass}"
+      role="dialog"
+      aria-modal="true"
+    >
+      {@render search()}
+    </div>
+  {/if}
+</div>

package/src/lib/index.ts

@@ -1,5 +1,17 @@
-export { default as Button } from './Button.svelte'
-export { default as Badge } from './Badge.svelte'
-export { default as Card } from './Card.svelte'
-export { default as NodeBadge } from './NodeBadge.svelte'
-export { default as Kbd } from './Kbd.svelte'
+export { default as Button } from "./Button.svelte";
+export { default as Badge } from "./Badge.svelte";
+export { default as Card } from "./Card.svelte";
+export { default as NodeBadge } from "./NodeBadge.svelte";
+export { default as Kbd } from "./Kbd.svelte";
+export { default as SplitView } from "./SplitView.svelte";
+export { default as ListRow } from "./ListRow.svelte";
+export { default as SectionHeading } from "./SectionHeading.svelte";
+export { default as Pill } from "./Pill.svelte";
+export { default as NavItem } from "./NavItem.svelte";
+export { default as EmptyState } from "./EmptyState.svelte";
+export { default as LoadingState } from "./LoadingState.svelte";
+export {
+  splitViewGridClass,
+  isSearchShortcut,
+  SPLIT_VIEW_BREAKPOINT_REM,
+} from "./split-view";

package/src/lib/split-view.ts

@@ -0,0 +1,38 @@
+// Pure, framework-free helpers for the `SplitView` shell, kept separate from
+// the component so the grid math and the keyboard idiom can be unit-tested
+// without mounting Svelte.
+
+/** Container width (in `rem`) at/above which both panes show; below, one column. */
+export const SPLIT_VIEW_BREAKPOINT_REM = 52;
+
+/**
+ * Tailwind grid-template class for the two-pane shell.
+ *
+ * - `true`  → always a single column
+ * - `false` → always two columns (`13rem | minmax(0,1fr)`)
+ * - omitted → responsive: one column below the container breakpoint, two at or
+ *   above it (Tailwind v4 container query — the shell measures its own width,
+ *   so it collapses in a narrow embed, not just a narrow viewport).
+ *
+ * Each branch returns a contiguous literal so Tailwind's source scanner emits
+ * the utilities — never assemble these class strings via interpolation.
+ */
+export function splitViewGridClass(collapsed?: boolean): string {
+  if (collapsed === true) return "grid-cols-1";
+  if (collapsed === false) return "grid-cols-[13rem_minmax(0,1fr)]";
+  return "grid-cols-1 @min-[52rem]:grid-cols-[13rem_minmax(0,1fr)]";
+}
+
+/**
+ * The default "Cmd+K idiom": ⌘K on macOS, Ctrl+K elsewhere, with no Shift or
+ * Alt. Returns true when a keydown should focus the inline search (or toggle
+ * the search overlay) of a `SplitView`.
+ */
+export function isSearchShortcut(e: KeyboardEvent): boolean {
+  return (
+    Boolean(e.metaKey || e.ctrlKey) &&
+    !e.shiftKey &&
+    !e.altKey &&
+    e.key.toLowerCase() === "k"
+  );
+}