@frockbot/client-ui 0.0.0 → 0.1.1

package/package.json

@@ -1,14 +1,32 @@
 {
   "name": "@frockbot/client-ui",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "vue-tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/client-core": "0.1.1",
+    "markdown-it": "15.0.1",
+    "vue": "3.5.41"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "typescript": "5.9.3",
+    "vue-tsc": "3.3.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/client-ui"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/UiAnchor.vue

@@ -0,0 +1,159 @@
+<script setup lang="ts">
+/**
+ * One deep-linkable settings row or section.
+ *
+ * It gives its content a stable DOM id, offers a copy-link control, and
+ * highlights itself when a link resolves to it. Two things can make it the
+ * target: the shell announcing an anchor after it opened the surface, and the
+ * document's own fragment at the moment this row mounts — a panel loads its
+ * state asynchronously, so a row frequently appears *after* the link that
+ * named it was handled, and polling for it from the shell would be the wrong
+ * side of the seam.
+ */
+import { onBeforeUnmount, onMounted, ref } from "vue";
+import UiIconButton from "./UiIconButton.vue";
+import {
+  UI_ANCHOR_EVENT,
+  UI_ANCHOR_HIGHLIGHT_MS,
+  type UiAnchorEvent,
+} from "./anchors.js";
+
+const props = withDefaults(
+  defineProps<{
+    /** The fragment identifier, and this element's DOM id. */
+    anchor: string;
+    /** What the row is called; used for the copy control's accessible name. */
+    label: string;
+    /** The link the copy control puts on the clipboard. */
+    href?: string;
+    /** An `article` for a card, a `section` for a titled block. */
+    as?: "div" | "section" | "article";
+  }>(),
+  { href: undefined, as: "div" },
+);
+
+/*
+ * Two states, deliberately. `highlighted` is the flash and fades; `targeted`
+ * records that a link resolved to this row and stays, so a reader who looks
+ * away can still tell which row they were sent to — and so a test can assert
+ * the link landed without racing the fade.
+ */
+const highlighted = ref(false);
+const targeted = ref(false);
+const copied = ref(false);
+const root = ref<HTMLElement>();
+let highlightTimer: ReturnType<typeof setTimeout> | undefined;
+let copiedTimer: ReturnType<typeof setTimeout> | undefined;
+
+function reveal(): void {
+  targeted.value = true;
+  highlighted.value = true;
+  clearTimeout(highlightTimer);
+  highlightTimer = setTimeout(() => {
+    highlighted.value = false;
+  }, UI_ANCHOR_HIGHLIGHT_MS);
+  const element = root.value;
+  if (!element?.scrollIntoView) return;
+  const reduced =
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+  element.scrollIntoView({
+    behavior: reduced ? "auto" : "smooth",
+    block: "nearest",
+  });
+}
+
+function onAnnounced(event: Event): void {
+  if ((event as UiAnchorEvent).detail === props.anchor) reveal();
+}
+
+onMounted(() => {
+  window.addEventListener(UI_ANCHOR_EVENT, onAnnounced);
+  const fragment = decodeURIComponent(
+    window.location.hash.replace(/^#/u, "") || "",
+  );
+  if (fragment === props.anchor) reveal();
+});
+
+onBeforeUnmount(() => {
+  window.removeEventListener(UI_ANCHOR_EVENT, onAnnounced);
+  clearTimeout(highlightTimer);
+  clearTimeout(copiedTimer);
+});
+
+async function copyLink(): Promise<void> {
+  if (!props.href) return;
+  const absolute = new URL(props.href, window.location.href).href;
+  try {
+    await navigator.clipboard.writeText(absolute);
+    copied.value = true;
+    clearTimeout(copiedTimer);
+    copiedTimer = setTimeout(() => {
+      copied.value = false;
+    }, UI_ANCHOR_HIGHLIGHT_MS);
+  } catch {
+    // Clipboard access can be refused, and a refused copy is not a product
+    // failure: the row is already addressable, and the User can read the link
+    // off the address bar after following it once.
+    copied.value = false;
+  }
+}
+</script>
+
+<template>
+  <component
+    :is="as"
+    :id="anchor"
+    ref="root"
+    class="ui-anchor"
+    :class="{ 'ui-anchor--target': highlighted }"
+    :data-anchor-target="targeted ? 'true' : undefined"
+  >
+    <slot />
+    <UiIconButton
+      v-if="href"
+      class="ui-anchor__copy"
+      :icon="copied ? 'check' : 'link'"
+      :label="copied ? `Copied link to ${label}` : `Copy link to ${label}`"
+      size="sm"
+      @click="copyLink"
+    />
+  </component>
+</template>
+
+<style scoped>
+.ui-anchor {
+  position: relative;
+  border-radius: var(--frock-radius-control);
+  scroll-margin-block: 12px;
+  transition:
+    background-color var(--frock-motion-panel),
+    box-shadow var(--frock-motion-panel);
+}
+
+.ui-anchor--target {
+  background: var(--frock-surface-accent-soft);
+  box-shadow: 0 0 0 2px var(--frock-border-focus);
+}
+
+.ui-anchor__copy {
+  position: absolute;
+  top: 0;
+  right: 0;
+  opacity: 0;
+  transition: opacity var(--frock-motion-fast);
+}
+
+.ui-anchor:hover .ui-anchor__copy,
+.ui-anchor:focus-within .ui-anchor__copy,
+.ui-anchor[data-anchor-target] .ui-anchor__copy {
+  opacity: 1;
+}
+
+@media (hover: none) {
+  .ui-anchor__copy {
+    opacity: 1;
+  }
+}
+</style>

package/src/UiButton.vue

@@ -0,0 +1,78 @@
+<script setup lang="ts">
+withDefaults(
+  defineProps<{
+    type?: "button" | "submit" | "reset";
+    variant?: "primary" | "secondary" | "danger" | "ghost";
+    disabled?: boolean;
+  }>(),
+  { type: "button", variant: "secondary", disabled: false },
+);
+</script>
+
+<template>
+  <button
+    :type="type"
+    class="ui-button"
+    :class="`ui-button--${variant}`"
+    :disabled="disabled"
+  >
+    <slot />
+  </button>
+</template>
+
+<style scoped>
+.ui-button {
+  min-height: 36px;
+  padding: 0 16px;
+  border: 1px solid transparent;
+  border-radius: var(--frock-radius-control);
+  color: var(--frock-text);
+  background: transparent;
+  font-size: var(--frock-text-base);
+  font-weight: 700;
+  white-space: nowrap;
+  cursor: pointer;
+  transition:
+    background-color var(--frock-motion-fast),
+    border-color var(--frock-motion-fast),
+    color var(--frock-motion-fast),
+    transform var(--frock-motion-fast);
+}
+
+.ui-button:active:not(:disabled) {
+  transform: scale(0.97);
+}
+
+.ui-button--primary {
+  color: var(--frock-on-accent);
+  background: var(--frock-action-primary);
+}
+
+.ui-button--primary:hover:not(:disabled) {
+  background: var(--frock-action-primary-hover);
+}
+
+.ui-button--primary:active:not(:disabled) {
+  background: var(--frock-action-primary-pressed);
+}
+
+.ui-button--secondary {
+  border-color: var(--frock-border);
+  background: var(--frock-surface-raised);
+}
+
+.ui-button--secondary:hover:not(:disabled),
+.ui-button--ghost:hover:not(:disabled) {
+  background: var(--frock-surface-subtle);
+}
+
+.ui-button--danger {
+  color: var(--frock-danger-text);
+  background: var(--frock-danger-surface);
+}
+
+.ui-button:disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+</style>

package/src/UiField.vue

@@ -0,0 +1,59 @@
+<script setup lang="ts">
+defineProps<{
+  label: string;
+  hint?: string;
+}>();
+</script>
+
+<template>
+  <label class="ui-field">
+    <span class="ui-field__label">
+      {{ label }} <small v-if="hint">{{ hint }}</small>
+    </span>
+    <slot />
+  </label>
+</template>
+
+<style scoped>
+.ui-field {
+  display: flex;
+  flex-direction: column;
+  gap: 7px;
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-sm);
+  font-weight: 700;
+}
+
+.ui-field__label small {
+  color: var(--frock-text-subtle);
+  font-weight: 500;
+}
+
+.ui-field :deep(input),
+.ui-field :deep(textarea),
+.ui-field :deep(select) {
+  width: 100%;
+  border: 1px solid var(--frock-border-strong);
+  border-radius: var(--frock-radius-control);
+  outline: none;
+  padding: 10px 12px;
+  color: var(--frock-text);
+  background: var(--frock-surface-raised);
+  font-size: var(--frock-text-md);
+  transition:
+    border-color var(--frock-motion-fast),
+    box-shadow var(--frock-motion-fast);
+}
+
+.ui-field :deep(input:focus),
+.ui-field :deep(textarea:focus),
+.ui-field :deep(select:focus) {
+  border-color: var(--frock-border-focus);
+  box-shadow: 0 0 0 3px var(--frock-focus-ring);
+}
+
+.ui-field :deep(textarea) {
+  resize: vertical;
+  line-height: var(--frock-leading-normal);
+}
+</style>

package/src/UiIcon.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { uiIconPaths, type UiIconName } from "./icons.js";
+
+const props = withDefaults(
+  defineProps<{
+    name: UiIconName;
+    /** Rendered box in CSS pixels. Defaults to the medium icon token. */
+    size?: number | "sm" | "md" | "lg";
+    /** Stroke width in 24-unit viewBox units. */
+    weight?: number;
+  }>(),
+  { size: "md", weight: 1.75 },
+);
+
+const dimension = computed(() =>
+  typeof props.size === "number"
+    ? `${props.size}px`
+    : `var(--frock-icon-${props.size})`,
+);
+const segments = computed(() => uiIconPaths[props.name]);
+const filled = computed(() => props.name === "stop");
+</script>
+
+<template>
+  <svg
+    class="ui-icon"
+    :style="{ width: dimension, height: dimension }"
+    viewBox="0 0 24 24"
+    :fill="filled ? 'currentColor' : 'none'"
+    stroke="currentColor"
+    :stroke-width="weight"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+    focusable="false"
+  >
+    <path v-for="(segment, index) in segments" :key="index" :d="segment" />
+  </svg>
+</template>
+
+<style scoped>
+.ui-icon {
+  display: block;
+  flex: 0 0 auto;
+}
+</style>

package/src/UiIconButton.vue

@@ -0,0 +1,141 @@
+<script setup lang="ts">
+import UiIcon from "./UiIcon.vue";
+import type { UiIconName } from "./icons.js";
+
+/**
+ * A square control that holds exactly one icon. The icon is centred by the
+ * grid, not by line metrics, so it never drifts the way a text glyph does.
+ * `label` is mandatory because the control has no visible text.
+ */
+withDefaults(
+  defineProps<{
+    label: string;
+    icon?: UiIconName;
+    type?: "button" | "submit" | "reset";
+    /** ghost: no chrome until hover. outlined: hairline ring. primary: accent fill. */
+    variant?: "ghost" | "outlined" | "primary";
+    size?: "sm" | "md" | "lg";
+    shape?: "round" | "square";
+    disabled?: boolean;
+    pressed?: boolean;
+  }>(),
+  {
+    icon: undefined,
+    type: "button",
+    variant: "ghost",
+    size: "md",
+    shape: "round",
+    disabled: false,
+    pressed: undefined,
+  },
+);
+</script>
+
+<template>
+  <button
+    :type="type"
+    class="ui-icon-button"
+    :class="[
+      `ui-icon-button--${variant}`,
+      `ui-icon-button--${size}`,
+      `ui-icon-button--${shape}`,
+    ]"
+    :disabled="disabled"
+    :aria-label="label"
+    :aria-pressed="pressed"
+    :title="label"
+  >
+    <slot>
+      <UiIcon v-if="icon" :name="icon" :size="size === 'sm' ? 'sm' : 'md'" />
+    </slot>
+  </button>
+</template>
+
+<style scoped>
+.ui-icon-button {
+  display: grid;
+  flex: 0 0 auto;
+  place-items: center;
+  padding: 0;
+  border: 1px solid transparent;
+  color: var(--frock-text-muted);
+  background: transparent;
+  cursor: pointer;
+  -webkit-app-region: no-drag;
+  transition:
+    background-color var(--frock-motion-fast),
+    border-color var(--frock-motion-fast),
+    color var(--frock-motion-fast),
+    transform var(--frock-motion-fast);
+}
+
+.ui-icon-button--sm {
+  width: var(--frock-control-sm);
+  height: var(--frock-control-sm);
+}
+
+.ui-icon-button--md {
+  width: var(--frock-control-md);
+  height: var(--frock-control-md);
+}
+
+.ui-icon-button--lg {
+  width: var(--frock-control-lg);
+  height: var(--frock-control-lg);
+}
+
+.ui-icon-button--round {
+  border-radius: 999px;
+}
+
+.ui-icon-button--square {
+  border-radius: var(--frock-radius-control);
+}
+
+.ui-icon-button--outlined {
+  border-color: var(--frock-border);
+  background: var(--frock-surface);
+}
+
+.ui-icon-button--primary {
+  color: var(--frock-on-accent);
+  background: var(--frock-action-primary);
+}
+
+.ui-icon-button--ghost:hover:not(:disabled),
+.ui-icon-button--outlined:hover:not(:disabled) {
+  color: var(--frock-text);
+  background: var(--frock-fill-hover);
+}
+
+.ui-icon-button--primary:hover:not(:disabled) {
+  background: var(--frock-action-primary-hover);
+}
+
+.ui-icon-button--primary:active:not(:disabled) {
+  background: var(--frock-action-primary-pressed);
+}
+
+.ui-icon-button:active:not(:disabled) {
+  transform: scale(0.94);
+}
+
+.ui-icon-button--ghost:active:not(:disabled),
+.ui-icon-button--outlined:active:not(:disabled) {
+  background: var(--frock-fill-pressed);
+}
+
+.ui-icon-button[aria-pressed="true"] {
+  color: var(--frock-action-primary-hover);
+  background: var(--frock-surface-accent);
+}
+
+.ui-icon-button:disabled {
+  color: var(--frock-text-disabled);
+  cursor: default;
+}
+
+.ui-icon-button--primary:disabled {
+  background: var(--frock-surface-disabled);
+}
+</style>

package/src/UiMarkdown.vue

@@ -0,0 +1,156 @@
+<script setup lang="ts">
+import { computed } from "vue";
+import { renderMarkdown } from "./markdown.js";
+
+/**
+ * Renders Markdown text. The HTML comes from `renderMarkdown`, which escapes
+ * every author tag, so `v-html` here injects only markup the parser produced.
+ */
+const props = defineProps<{ text: string }>();
+const html = computed(() => renderMarkdown(props.text));
+</script>
+
+<template>
+  <!-- eslint-disable-next-line vue/no-v-html -->
+  <div class="ui-markdown" v-html="html" />
+</template>
+
+<style scoped>
+.ui-markdown {
+  overflow-wrap: anywhere;
+  /* The bubble sets pre-wrap for plain text; rendered Markdown owns its own
+     whitespace, so it opts back out. */
+  white-space: normal;
+}
+
+.ui-markdown :deep(> :first-child) {
+  margin-top: 0;
+}
+
+.ui-markdown :deep(> :last-child) {
+  margin-bottom: 0;
+}
+
+.ui-markdown :deep(p) {
+  margin: 0 0 8px;
+}
+
+.ui-markdown :deep(ul),
+.ui-markdown :deep(ol) {
+  margin: 0 0 8px;
+  padding-left: 20px;
+}
+
+.ui-markdown :deep(li) {
+  margin: 2px 0;
+}
+
+.ui-markdown :deep(li > ul),
+.ui-markdown :deep(li > ol) {
+  margin-bottom: 0;
+}
+
+.ui-markdown :deep(h1),
+.ui-markdown :deep(h2),
+.ui-markdown :deep(h3),
+.ui-markdown :deep(h4) {
+  margin: 14px 0 6px;
+  font-weight: 600;
+  line-height: var(--frock-leading-snug);
+}
+
+.ui-markdown :deep(h1) {
+  font-size: var(--frock-text-xl);
+  letter-spacing: var(--frock-tracking-display);
+}
+
+.ui-markdown :deep(h2) {
+  font-size: var(--frock-text-lg);
+}
+
+.ui-markdown :deep(h3) {
+  font-size: var(--frock-text-md);
+}
+
+.ui-markdown :deep(h4) {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-base);
+}
+
+.ui-markdown :deep(strong) {
+  font-weight: 650;
+}
+
+.ui-markdown :deep(a) {
+  color: var(--frock-action-primary-hover);
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.ui-markdown :deep(code) {
+  padding: 1px 5px;
+  border-radius: 6px;
+  background: var(--frock-fill-hover);
+  font-family: var(--frock-font-mono);
+  font-size: var(--frock-text-sm);
+}
+
+.ui-markdown :deep(pre) {
+  overflow-x: auto;
+  margin: 0 0 8px;
+  padding: 10px 12px;
+  border: 1px solid var(--frock-border);
+  border-radius: var(--frock-radius-control);
+  background: var(--frock-surface);
+  scrollbar-color: var(--frock-scrollbar) transparent;
+  scrollbar-width: thin;
+}
+
+.ui-markdown :deep(pre code) {
+  display: block;
+  padding: 0;
+  border-radius: 0;
+  background: transparent;
+  line-height: var(--frock-leading-snug);
+  white-space: pre;
+}
+
+.ui-markdown :deep(blockquote) {
+  margin: 0 0 8px;
+  padding: 2px 0 2px 12px;
+  border-left: 2px solid var(--frock-border-strong);
+  color: var(--frock-text-muted);
+}
+
+.ui-markdown :deep(table) {
+  display: block;
+  overflow-x: auto;
+  max-width: 100%;
+  margin: 0 0 8px;
+  border-collapse: collapse;
+  font-size: var(--frock-text-sm);
+}
+
+.ui-markdown :deep(th),
+.ui-markdown :deep(td) {
+  padding: 5px 9px;
+  border: 1px solid var(--frock-border);
+  text-align: left;
+}
+
+.ui-markdown :deep(th) {
+  background: var(--frock-surface);
+  font-weight: 600;
+}
+
+.ui-markdown :deep(hr) {
+  margin: 12px 0;
+  border: 0;
+  border-top: 1px solid var(--frock-border);
+}
+
+.ui-markdown :deep(img) {
+  max-width: 100%;
+  border-radius: var(--frock-radius-control);
+}
+</style>

package/src/UiSidebarOverlay.vue

@@ -0,0 +1,130 @@
+<script setup lang="ts">
+import { nextTick, onBeforeUnmount, ref, watch } from "vue";
+import UiIconButton from "./UiIconButton.vue";
+
+const props = defineProps<{
+  open: boolean;
+  title: string;
+}>();
+const emit = defineEmits<{ close: [] }>();
+const panel = ref<HTMLElement>();
+let restoreFocus: HTMLElement | undefined;
+
+watch(
+  () => props.open,
+  async (open, previous) => {
+    if (open && !previous) {
+      restoreFocus =
+        document.activeElement instanceof HTMLElement
+          ? document.activeElement
+          : undefined;
+      await nextTick();
+      panel.value?.querySelector<HTMLElement>("[data-surface-close]")?.focus();
+    } else if (!open && previous) {
+      restoreFocus?.focus();
+      restoreFocus = undefined;
+    }
+  },
+  { flush: "post" },
+);
+
+function onKeydown(event: KeyboardEvent): void {
+  if (event.key !== "Escape") return;
+  event.preventDefault();
+  emit("close");
+}
+
+onBeforeUnmount(() => restoreFocus?.focus());
+</script>
+
+<template>
+  <Transition name="ui-surface">
+    <aside
+      v-if="open"
+      ref="panel"
+      class="ui-sidebar-overlay"
+      role="region"
+      aria-labelledby="ui-sidebar-overlay-title"
+      @keydown="onKeydown"
+    >
+      <header class="ui-sidebar-overlay__header">
+        <h2 id="ui-sidebar-overlay-title">{{ title }}</h2>
+        <UiIconButton
+          data-surface-close
+          icon="close"
+          label="Close panel"
+          @click="emit('close')"
+        />
+      </header>
+      <div class="ui-sidebar-overlay__content">
+        <slot />
+      </div>
+    </aside>
+  </Transition>
+</template>
+
+<style scoped>
+.ui-sidebar-overlay {
+  position: absolute;
+  z-index: var(--frock-layer-surface);
+  inset: 0 auto 0 0;
+  display: flex;
+  width: min(var(--frock-settings-width), 100vw);
+  min-height: 0;
+  flex-direction: column;
+  border-right: 1px solid var(--frock-border);
+  color: var(--frock-text);
+  background: var(--frock-surface);
+  box-shadow: var(--frock-shadow-panel);
+}
+
+.ui-sidebar-overlay__header {
+  display: grid;
+  min-height: var(--frock-titlebar-height);
+  flex: 0 0 auto;
+  grid-template-columns: minmax(0, 1fr) auto;
+  align-items: center;
+  gap: 16px;
+  padding: 0 18px 0 24px;
+  border-bottom: 1px solid var(--frock-border);
+}
+
+.ui-sidebar-overlay__header h2 {
+  overflow: hidden;
+  margin: 0;
+  font-family: var(--frock-font-display);
+  font-size: var(--frock-text-2xl);
+  font-weight: 400;
+  letter-spacing: var(--frock-tracking-display);
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+.ui-sidebar-overlay__content {
+  min-height: 0;
+  flex: 1;
+  overflow-y: auto;
+  scrollbar-color: var(--frock-scrollbar) transparent;
+  scrollbar-width: thin;
+}
+
+.ui-surface-enter-active,
+.ui-surface-leave-active {
+  transition:
+    transform var(--frock-motion-panel),
+    opacity var(--frock-motion-panel);
+}
+
+.ui-surface-enter-from,
+.ui-surface-leave-to {
+  opacity: 0;
+  transform: translateX(-18px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-surface-enter-active,
+  .ui-surface-leave-active {
+    transition-duration: 0.01ms;
+  }
+}
+</style>

package/src/UiSkeleton.vue

@@ -0,0 +1,68 @@
+<script setup lang="ts">
+/**
+ * A loading placeholder that keeps the final layout's footprint so content
+ * does not jump when it arrives. Compose several to sketch a row or a card.
+ */
+withDefaults(
+  defineProps<{
+    width?: string;
+    height?: string;
+    shape?: "text" | "block" | "circle";
+  }>(),
+  { width: "100%", height: undefined, shape: "text" },
+);
+</script>
+
+<template>
+  <span
+    class="ui-skeleton"
+    :class="`ui-skeleton--${shape}`"
+    :style="{ width, height }"
+    aria-hidden="true"
+  />
+</template>
+
+<style scoped>
+.ui-skeleton {
+  position: relative;
+  display: block;
+  overflow: hidden;
+  flex: 0 0 auto;
+  background: var(--frock-skeleton);
+}
+
+.ui-skeleton--text {
+  height: 0.75em;
+  border-radius: 4px;
+}
+
+.ui-skeleton--block {
+  height: var(--frock-control-md);
+  border-radius: var(--frock-radius-control);
+}
+
+.ui-skeleton--circle {
+  width: var(--frock-avatar-md);
+  height: var(--frock-avatar-md);
+  border-radius: 999px;
+}
+
+.ui-skeleton::after {
+  position: absolute;
+  inset: 0;
+  content: "";
+  background: linear-gradient(
+    90deg,
+    transparent,
+    var(--frock-skeleton-shine),
+    transparent
+  );
+  animation: frock-shimmer 1.4s ease-in-out infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-skeleton::after {
+    animation: none;
+  }
+}
+</style>

package/src/anchors.ts

@@ -0,0 +1,23 @@
+/**
+ * The client-side half of the settings deep-link scheme.
+ *
+ * The scheme itself lives in `@frockbot/plugin-shell/settings-links`, which
+ * `client-ui` must not depend on — a primitive cannot import the shell. What
+ * the primitives need is narrower: the name of the event the shell fires when
+ * a link resolves, so an anchored row can highlight itself without either side
+ * reaching into the other's styles.
+ */
+
+/** The window event a resolved settings link fires. `detail` is the anchor. */
+export const UI_ANCHOR_EVENT = "frockbot:anchor";
+
+export type UiAnchorEvent = CustomEvent<string>;
+
+/** Tell every mounted anchor that this one is the link's target. */
+export function announceUiAnchor(anchor: string): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(UI_ANCHOR_EVENT, { detail: anchor }));
+}
+
+/** How long an anchored row stays highlighted after a link resolves to it. */
+export const UI_ANCHOR_HIGHLIGHT_MS = 2_600;

package/src/env.d.ts

@@ -0,0 +1,6 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+
+  const component: DefineComponent;
+  export default component;
+}

package/src/icons.ts

@@ -0,0 +1,72 @@
+/**
+ * The shared icon set. Glyphs are 24-unit stroke paths so every icon shares
+ * the same optical weight and sits centred inside a control; plugins must not
+ * fall back to Unicode symbols, whose ink offsets differ per font.
+ */
+export type UiIconName =
+  | "arrow-down"
+  | "arrow-up"
+  | "check"
+  | "chevron-left"
+  | "chevrons-left"
+  | "chevrons-right"
+  | "close"
+  | "gear"
+  | "history"
+  | "link"
+  | "menu"
+  | "mic"
+  | "plugins"
+  | "plus"
+  | "refresh"
+  | "search"
+  | "sparkle"
+  | "stop"
+  | "user";
+
+export const uiIconPaths: Record<UiIconName, string[]> = {
+  "arrow-down": ["m19 12-7 7-7-7", "M12 5v14"],
+  "arrow-up": ["m5 12 7-7 7 7", "M12 19V5"],
+  check: ["M20 6 9 17l-5-5"],
+  "chevron-left": ["m15 18-6-6 6-6"],
+  "chevrons-left": ["m11 17-5-5 5-5", "m18 17-5-5 5-5"],
+  "chevrons-right": ["m6 17 5-5-5-5", "m13 17 5-5-5-5"],
+  close: ["M18 6 6 18", "m6 6 12 12"],
+  gear: [
+    "M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z",
+    "M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6z",
+  ],
+  history: [
+    "M3 12a9 9 0 1 0 9-9 9.75 9.75 0 0 0-6.74 2.74L3 8",
+    "M3 3v5h5",
+    "M12 7v5l4 2",
+  ],
+  link: [
+    "M10 13a5 5 0 0 0 7.07 0l2.83-2.83a5 5 0 0 0-7.07-7.07L11.5 4.5",
+    "M14 11a5 5 0 0 0-7.07 0l-2.83 2.83a5 5 0 0 0 7.07 7.07L12.5 19.5",
+  ],
+  menu: ["M4 7h16", "M4 12h16", "M4 17h16"],
+  mic: [
+    "M12 2a3 3 0 0 0-3 3v7a3 3 0 0 0 6 0V5a3 3 0 0 0-3-3z",
+    "M19 10v2a7 7 0 0 1-14 0v-2",
+    "M12 19v3",
+  ],
+  plugins: [
+    "M4 4h6v6H4z",
+    "M14 4h6v6h-6z",
+    "M4 14h6v6H4z",
+    "M17 14v6",
+    "M14 17h6",
+  ],
+  plus: ["M5 12h14", "M12 5v14"],
+  refresh: [
+    "M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8",
+    "M21 3v5h-5",
+    "M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16",
+    "M8 16H3v5",
+  ],
+  search: ["M11 19a8 8 0 1 0 0-16 8 8 0 0 0 0 16z", "m21 21-4.3-4.3"],
+  sparkle: ["M12 3l1.9 5.6 5.6 1.9-5.6 1.9L12 18l-1.9-5.6L4.5 10.5l5.6-1.9z"],
+  stop: ["M6 6h12v12H6z"],
+  user: ["M12 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8z", "M20 21a8 8 0 0 0-16 0"],
+};

package/src/index.ts

@@ -0,0 +1,17 @@
+export { default as UiSidebarOverlay } from "./UiSidebarOverlay.vue";
+export { default as UiAnchor } from "./UiAnchor.vue";
+export {
+  announceUiAnchor,
+  UI_ANCHOR_EVENT,
+  UI_ANCHOR_HIGHLIGHT_MS,
+  type UiAnchorEvent,
+} from "./anchors.js";
+export { default as UiButton } from "./UiButton.vue";
+export { default as UiField } from "./UiField.vue";
+export { default as UiIcon } from "./UiIcon.vue";
+export { uiIconPaths, type UiIconName } from "./icons.js";
+export { default as UiIconButton } from "./UiIconButton.vue";
+export { default as UiMarkdown } from "./UiMarkdown.vue";
+export { renderMarkdown } from "./markdown.js";
+export { default as UiSkeleton } from "./UiSkeleton.vue";
+export { createClientSurfaceRegistry } from "./surfaces.js";

package/src/markdown.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test";
+import { renderMarkdown } from "./markdown.js";
+
+describe("renderMarkdown", () => {
+  test("escapes author HTML instead of emitting it", () => {
+    const html = renderMarkdown('<img src=x onerror="alert(1)"> **bold**');
+
+    expect(html).not.toContain("<img");
+    expect(html).not.toContain('onerror="');
+    expect(html).toContain("&lt;img");
+    expect(html).toContain("<strong>bold</strong>");
+  });
+
+  test("opens links in a new context without window access", () => {
+    const html = renderMarkdown("[docs](https://example.com/docs)");
+
+    expect(html).toContain('href="https://example.com/docs"');
+    expect(html).toContain('target="_blank"');
+    expect(html).toContain('rel="noopener noreferrer"');
+  });
+
+  test("linkifies bare URLs with the same link attributes", () => {
+    const html = renderMarkdown("see https://example.com for more");
+
+    expect(html).toContain('<a href="https://example.com"');
+    expect(html).toContain('rel="noopener noreferrer"');
+  });
+
+  test("renders fenced code blocks and inline code", () => {
+    const html = renderMarkdown("```\nconst x = 1 < 2;\n```\n\nuse `bun test`");
+
+    expect(html).toContain("<pre><code>const x = 1 &lt; 2;");
+    expect(html).toContain("<code>bun test</code>");
+  });
+
+  test("keeps single newlines as breaks", () => {
+    expect(renderMarkdown("one\ntwo")).toContain("<br>");
+  });
+
+  test("renders lists", () => {
+    const html = renderMarkdown("- first\n- second");
+
+    expect(html).toContain("<ul>");
+    expect(html).toContain("<li>first</li>");
+  });
+});

package/src/markdown.ts

@@ -0,0 +1,34 @@
+import MarkdownIt from "markdown-it";
+
+/*
+ * Assistant text is Markdown. Rendering it needs no sanitizer because the
+ * parser never emits author HTML: `html: false` escapes every raw tag, and the
+ * only markup in the output is what markdown-it itself generates. `breaks`
+ * keeps single newlines meaningful the way chat clients do, and `typographer`
+ * stays off so code, paths, and quotes survive verbatim.
+ */
+const markdown = new MarkdownIt({
+  html: false,
+  linkify: true,
+  breaks: true,
+  typographer: false,
+});
+
+const defaultLinkOpen =
+  markdown.renderer.rules.link_open ??
+  ((tokens, index, options, _env, self) =>
+    self.renderToken(tokens, index, options));
+
+// Every link leaves the application, so it opens in a new context and is
+// denied access to this window through `opener`.
+markdown.renderer.rules.link_open = (tokens, index, options, env, self) => {
+  const token = tokens[index];
+  token.attrSet("target", "_blank");
+  token.attrSet("rel", "noopener noreferrer");
+  return defaultLinkOpen(tokens, index, options, env, self);
+};
+
+/** Renders Markdown to HTML that is safe to inject without a sanitizer. */
+export function renderMarkdown(text: string): string {
+  return markdown.render(text);
+}

package/src/surfaces.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { defineComponent } from "vue";
+import { createClientSurfaceRegistry } from "./surfaces.js";
+
+const Surface = defineComponent(() => () => null);
+
+describe("client surface registry", () => {
+  test("opens registered surfaces and closes a disposed active surface", () => {
+    const registry = createClientSurfaceRegistry();
+    const dispose = registry.register({
+      id: "bot-settings",
+      title: "Bot settings",
+      component: Surface,
+    });
+
+    expect(registry.has("bot-settings")).toBe(true);
+    registry.open("bot-settings");
+    expect(registry.active.value).toMatchObject({
+      id: "bot-settings",
+      title: "Bot settings",
+    });
+
+    dispose();
+    expect(registry.active.value).toBeUndefined();
+    expect(registry.activeId.value).toBeUndefined();
+  });
+
+  test("carries the declared placement and defaults to an overlay", () => {
+    const registry = createClientSurfaceRegistry();
+    registry.register({
+      id: "bot-settings",
+      title: "Bot settings",
+      component: Surface,
+      placement: "panel",
+    });
+    registry.register({
+      id: "plugins",
+      title: "Plugins",
+      component: Surface,
+    });
+
+    registry.open("bot-settings");
+    expect(registry.active.value?.placement).toBe("panel");
+    registry.open("plugins");
+    expect(registry.active.value?.placement).toBeUndefined();
+  });
+
+  test("rejects missing and duplicate surfaces", () => {
+    const registry = createClientSurfaceRegistry();
+    expect(() => registry.open("missing")).toThrow(
+      "client surface is unavailable: missing",
+    );
+    registry.register({
+      id: "plugins",
+      title: "Plugins",
+      component: Surface,
+    });
+    expect(() =>
+      registry.register({
+        id: "plugins",
+        title: "Another Plugins view",
+        component: Surface,
+      }),
+    ).toThrow("client surface is already registered: plugins");
+  });
+});

package/src/surfaces.ts

@@ -0,0 +1,48 @@
+import type {
+  ClientSurfaceRegistration,
+  ClientSurfaceRegistry,
+} from "@frockbot/client-core";
+import { computed, readonly, ref } from "vue";
+
+export function createClientSurfaceRegistry(): ClientSurfaceRegistry {
+  const registrations = new Map<string, ClientSurfaceRegistration>();
+  const activeId = ref<string>();
+  const active = computed(() => {
+    const id = activeId.value;
+    return id ? registrations.get(id) : undefined;
+  });
+
+  return {
+    active,
+    activeId: readonly(activeId),
+    register(registration: ClientSurfaceRegistration) {
+      const id = registration.id.trim();
+      if (!id) throw new Error("client surface id must be non-empty");
+      if (!registration.title.trim()) {
+        throw new Error("client surface title must be non-empty");
+      }
+      if (registrations.has(id)) {
+        throw new Error(`client surface is already registered: ${id}`);
+      }
+      const stored = { ...registration, id };
+      registrations.set(id, stored);
+      return () => {
+        if (registrations.get(id) !== stored) return;
+        registrations.delete(id);
+        if (activeId.value === id) activeId.value = undefined;
+      };
+    },
+    has(id: string) {
+      return registrations.has(id);
+    },
+    open(id: string) {
+      if (!registrations.has(id)) {
+        throw new Error(`client surface is unavailable: ${id}`);
+      }
+      activeId.value = id;
+    },
+    close() {
+      activeId.value = undefined;
+    },
+  };
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/client-ui
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.